rgoussu.dev
rgoussu@goussu: ~/library/go/toolchain
❯ ~/library/go/toolchain cat delve.md

Delve — the Go debugger

# Delve (dlv), the goroutine-aware Go debugger — debug/attach/test/core modes, DAP for IDEs, conditional breakpoints, and remote debugging in containers.

Conceptsaved 2026-08-09 #go#tooling#debugging

Overview

Delve is the Go debugger. Generic debuggers like gdb see OS threads and mangled stacks; Go multiplexes goroutines across threads, grows stacks dynamically, and passes arguments in registers — gdb misreports all of it. Delve understands the runtime's data structures natively: goroutines, channels, interfaces, and maps render as Go sees them.

Key points

  • Entry modes: dlv debug (compile without optimizations and run), dlv test (debug a test binary), dlv attach <pid> (live process), dlv exec (pre-built binary), dlv core <binary> <core> (post-mortem, pairs with GOTRACEBACK=crash).
  • Goroutine-native: goroutines lists all of them (with filters/grouping), goroutine <id> bt inspects any stack — the view gdb fundamentally lacks.
  • Conditional breakpoints: break file.go:42 then condition 1 order.ID == "x"; conditions can target goroutine state (e.g. by goroutine labels via runtime/pprof.Labels) to stop only the request you care about.
  • DAP server: dlv dap speaks the Debug Adapter Protocol — VS Code, GoLand, and Neovim all drive Delve underneath; there is one debugger, many frontends.
  • Remote/containers: run dlv exec --headless --listen=:2345 --accept-multiclient --api-version=2 in the container, connect with dlv connect or an IDE; map source paths with substitute-path when build and dev trees differ.
  • Build flags matter: debug builds want -gcflags="all=-N -l" (no optimizations, no inlining) or variables show as optimized away; dlv debug does this for you.

Examples

dlv test ./order -- -test.run TestRefund
(dlv) break refund.go:87
(dlv) condition 1 amount > 1000
(dlv) continue
(dlv) goroutines -with user   # goroutines currently in user code

Related

  • The go command & tool catalog — parent catalog of the toolchain.
  • gopls — the editor's other Go backend; gopls for editing, Delve (via DAP) for debugging.
  • jdb — the JVM counterpart, similarly wired into IDEs through a shared debug protocol.