The friction of rebuilding everything
You write a Go function, save the file, and run go run main.go. It takes three seconds. You fix a typo, save, run again. Three seconds. Now you add a dependency, run go mod tidy, and suddenly the build takes twelve seconds because Docker is downloading the entire internet again. The container is stateless by design, which is excellent for production deployments but terrible for a development loop. You need a way to keep the heavy lifting out of the way while you iterate.
Docker volumes solve this by separating persistent data from ephemeral containers. You mount your source code directly into the container for live editing, and you attach named volumes to the paths where Go stores its module cache and build cache. The container stays disposable. The cache survives. Your edit-compile-run cycle drops from seconds to milliseconds.
What a volume actually does
A Docker container runs on a layered filesystem. The base image provides the operating system and the Go toolchain. Any file you create inside the container lives in a writable top layer. When the container stops, that layer is discarded. Everything resets.
A volume breaks that cycle. It is a storage block managed by Docker that lives outside the container's filesystem layers. You attach it to a specific path inside the container. Files written to that path are stored in the volume, not in the ephemeral layer. When the container restarts, the volume is still there. When you spin up a brand new container with the same volume attached, it sees the exact same files.
For Go development, the heavy gear you want to preserve is the module cache and the build cache. Go compiles fast, but only if it remembers what it already compiled. The module cache stores downloaded dependencies. The build cache stores compiled object files. If you lose either one, Go falls back to network requests and full recompilation. Mounting volumes to those paths turns a twelve-second build into a two-second build.
The minimal setup
Here is the simplest command to spin up a Go development container with persistent caching. It creates two named volumes for Go's caches, binds your current directory to /app, sets the working directory, and drops you into a shell.
docker run -it --rm \
-v go-mod-cache:/go/pkg/mod \
-v go-build-cache:/root/.cache/go-build \
-v $(pwd):/app \
-w /app \
golang:1.23 \
bash
The -it flags allocate a pseudo-TTY and keep stdin open so you can interact with the shell. The --rm flag tells Docker to delete the container filesystem when you exit, leaving only the named volumes behind. The -v flags map storage to paths. The first two create named volumes that Docker manages in its own storage directory. The third uses a bind mount to link your host machine's current directory to /app inside the container. The -w flag sets the working directory so Go commands run against your source code instead of the container's default root.
Inside the container, run go mod download once to populate the module volume. After that, use go run or go build as usual. The first run downloads dependencies and compiles everything. Subsequent runs reuse the cached objects. The container stays lean. The cache stays heavy.
Volumes are cheap. Bind mounts are fast. Keep them separate.
What happens under the hood
When Docker executes the command, it checks its internal volume registry. If go-mod-cache does not exist, Docker creates it. It then mounts that volume to /go/pkg/mod inside the new container. The same happens for go-build-cache at /root/.cache/go-build. Your host directory is mounted to /app. The Go toolchain starts and reads its default cache paths. Go 1.23 defaults to /go/pkg/mod for modules and /root/.cache/go-build for build artifacts. The paths match the mounts.
When you run go mod download, the Go command checks /go/pkg/mod for existing packages. It finds nothing on the first run, so it fetches dependencies over the network and writes them to the volume. The next time you start a fresh container, Go checks the same path, finds the packages, and skips the network request.
The build cache works similarly. Go's compiler is incremental. It hashes every source file, every dependency version, and every compiler flag. If the hash matches a previously compiled object file, Go reuses it instead of running the compiler again. The object files live in /root/.cache/go-build. Because that path is backed by a named volume, the hash database and compiled binaries survive container restarts. You change one file, Go recompiles only that file and its direct dependents, and links the binary in under a second.
The bind mount at /app gives you live editing. Your host machine's filesystem driver translates changes to the container's view. Most modern setups use virtiofs or gVFS on macOS, and native 9p or virtiofs on Linux. The latency is low enough that go run picks up changes immediately. You do not need to rebuild the container image to test a new function.
Go's cache paths are conventions, not magic. Trust the defaults. Mount the paths. Let the compiler do the heavy lifting.
A realistic development loop
In practice, you rarely type the full docker run command every time. You wrap it in a script or a Makefile so the workflow feels native. Here is a minimal Makefile that handles the dev loop, cache initialization, and cleanup.
# Dev target: starts the container and runs the app
dev:
docker run -it --rm \
-v go-mod-cache:/go/pkg/mod \
-v go-build-cache:/root/.cache/go-build \
-v $(shell pwd):/app \
-w /app \
golang:1.23 \
go run ./cmd/server
# Cache init: downloads modules once to warm the volume
cache-init:
docker run --rm \
-v go-mod-cache:/go/pkg/mod \
-v $(shell pwd):/app \
-w /app \
golang:1.23 \
go mod download
# Clean: removes the named volumes if you need a fresh start
clean:
docker volume rm go-mod-cache go-build-cache
The dev target runs your application directly. It attaches both cache volumes and the source bind mount. The cache-init target runs a headless container that only downloads modules. This is useful in CI pipelines or when you switch branches and need to populate the cache without starting the app. The clean target removes the named volumes. Use it when you suspect corrupted cache entries or when you want to verify that your build works from scratch.
Run make cache-init once after cloning the repository. Run make dev to start the server. Edit a file on your host. Press Ctrl+C in the terminal. Run make dev again. The build finishes instantly. The workflow mirrors a local Go installation, but your host machine stays clean. No system-wide Go installation. No conflicting toolchain versions. No permission headaches from installing packages globally.
Keep the Makefile in the repository. Share the workflow. Let everyone run the same environment.
Pitfalls and silent failures
Volumes solve persistence, but they introduce filesystem boundaries. The most common issue is a UID/GID mismatch. Docker runs containers as root by default. If your host machine runs as a non-root user, the bind mount at /app may have different ownership than the files inside the container. Go's compiler tries to write cache files to /root/.cache/go-build, which works fine because the container runs as root. But if you mount a custom cache path owned by your host user, the Go toolchain may fail with permission denied when trying to write build artifacts.
The compiler rejects the build with a permission denied error when the cache directory is not writable by the container's user. Fix it by either running the container with --user $(id -u):$(id -g) or by ensuring the volume is created with the correct ownership. Most developers stick to the default root user inside the container and accept that the cache volumes will be owned by root on the host. It is a safe tradeoff for development.
Another pitfall is filesystem performance on macOS and Windows. Docker Desktop runs a Linux VM under the hood. Bind mounts cross the VM boundary, which adds latency. Large projects with thousands of small files may feel sluggish. The module cache and build cache live on named volumes, which stay inside the VM's filesystem. They perform well. The bind mount for source code is the bottleneck. If you notice slow go run times, move your project directory to a location that Docker Desktop optimizes, or switch to a native Linux environment.
Goroutine leaks and context cancellation do not disappear just because you are in a container. If your Go application spawns background workers that wait on channels, and you stop the container abruptly, those goroutines vanish with the process. The volume persists, but the in-memory state does not. Always design your application to handle graceful shutdowns. Pass a context.Context as the first parameter to long-running functions. Respect cancellation signals. The container lifecycle is fast. Your application should be too.
Context is plumbing. Run it through every long-lived call site.
When to use volumes versus alternatives
Use named Docker volumes when you need persistent storage that survives container recreation and you want Docker to manage the underlying storage path. Use bind mounts when you need live editing of source code and you want changes on your host machine to appear instantly inside the container. Use Docker Compose when your application requires multiple services like a database or message broker and you want to define the entire stack in a single YAML file. Use a local Go installation when you are working on a small script, contributing to the Go standard library, or you need direct access to system-level debugging tools like delve without container overhead. Use a CI runner with cached volumes when you want fast pipeline builds that reuse dependencies across commits without polluting developer machines.
Pick the tool that matches the boundary you are trying to cross. Keep caches in volumes. Keep code in bind mounts. Keep production images clean.