Go Builds Packages, Not Files — Here’s Why That Matters

Introduction: The Illusion of Simplicity You probably type go build or go run dozens of times every week without thinking much about what happens under the hood. On the surface, these commands feel almost magical: you press Enter, and suddenly your code is compiled, linked, and - sometimes - executed. But beneath that simplicity lies a carefully orchestrated system, optimized to make your life as a developer easier while also being fast and predictable for machines. go build go run Understanding how Go handles building, running, and caching code isn't just an academic exercise. It explains why incremental builds are so fast, why CI pipelines behave consistently, and why sometimes a seemingly trivial change can trigger a full recompilation. This article walks through the modern Go toolchain as it exists today, presenting a mental model you can trust. By the end, you'll have a clear picture of: how Go resolves dependencies and structures your code into packages, how compilation and linking work behind the scenes, why the build cache is so reliable, and what actually happens when you type go build or go run. how Go resolves dependencies and structures your code into packages, how compilation and linking work behind the scenes, why the build cache is so reliable, and what actually happens when you type go build or go run. go build go run If you've ever been curious about why Go builds "just work" or why your temporary go run binaries seem almost instantaneous, this is the deep dive that connects the dots - for humans and machines alike. go run The Go Toolchain Mental Model At first glance, go build, go run, and go test look like separate commands, each with its own behavior. In reality, they are just frontends for the same underlying pipeline. Every Go command goes through a predictable sequence: it loads modules, resolves package dependencies, compiles packages, optionally links them into an executable, and sometimes executes the result. The differences between commands mostly come down to what happens to the final artifact, not the mechanics of building it. go build go run go test same underlying pipeline what happens to the final artifact A key concept to internalize is that Go builds packages, not individual files. Every .go file in a package is treated collectively, and the package itself is the unit that the compiler and build cache track. This has several consequences: Go builds packages, not individual files Modifying any single file in a package can trigger a rebuild of the entire package. Packages become the natural boundaries for caching and parallel compilation. Small, focused packages tend to scale better in large codebases because the compiler can reuse more cached results. Modifying any single file in a package can trigger a rebuild of the entire package. Packages become the natural boundaries for caching and parallel compilation. Small, focused packages tend to scale better in large codebases because the compiler can reuse more cached results. The pipeline is conceptually simple, but highly optimized: Go knows exactly what needs recompilation and what can be reused, which is why incremental builds feel almost instantaneous. You can think of the toolchain as a smart coordinator: it orchestrates compiling, linking, caching, and execution so you rarely have to worry about the details. Once you internalize this mental model, the behavior of go build and go run stops feeling like magic and starts making predictable sense. smart coordinator go build go run From go.mod to a Build Plan go.mod Before Go ever touches your source files, it needs to figure out what to build and in what order. This begins with the module system, centered around your go.mod and go.sum files. These files define the module graph, which is the full dependency tree of your project, along with precise versions for every module. By reading these files, the Go toolchain knows exactly which packages are part of your build and which external code to fetch, verify, and incorporate. go.mod go.sum module graph Once the module graph is loaded, Go evaluates each package to determine its source set. This includes every .go file that belongs to the package, filtered by build tags, operating system, architecture, and any constraints you've specified. Only after this evaluation does the compiler know what code it actually needs to process. This ensures that your builds are deterministic: the same go build command run on different machines produces identical results, assuming the same module versions. go build An important aspect of modern Go is the role of the go directive in go.mod. This directive declares the minimum Go version your module is designed for. It influences several characteristics of the build: language semantics, compiler behavior, and even static analysis. Depending on the go directive, language semantics, compiler behavior, and checks can differ - the toolchain enforces these during compilation. This is part of Go's focus on reproducibility, ensuring that your code behaves consistently across environments. go go.mod go By the end of this stage, the toolchain has a complete, ordered build plan: it knows which packages to compile, in what sequence, and which files belong to each package. With this information in hand, it moves on to the next step: compiling packages and linking them into binaries, confident that nothing will be missed or miscompiled. complete, ordered build plan Compilation and Linking in Practice Once Go has the build plan from the module system, it begins turning your code into something the machine can execute. This happens in two distinct stages: compilation and linking. Understanding these stages is key to appreciating why Go builds are fast, deterministic, and scalable. Compilation Is Per-Package Go compiles one package at a time. Each package - whether it's part of your project or an external dependency - is treated as an independent unit. The compiler produces intermediate artifacts for every package, which are stored in the build cache. This means that if a package hasn't changed since the last build, Go can skip recompiling it entirely, even if other packages that depend on it are being rebuilt. one package at a time intermediate artifacts Parallelism is another advantage of this per-package approach: since the compiler knows the dependency graph, it can compile multiple independent packages concurrently, fully leveraging multi-core CPUs. This is why large Go projects often feel surprisingly fast to build: a lot of work is done in parallel, and nothing is recompiled unnecessarily. Linking Is Selective Linking is the process of combining compiled packages into a single executable. Go only links main packages into binaries. Library packages never get linked on their own, they exist purely as reusable artifacts for other packages. This distinction is important: when you run go build ./... on a project, Go may compile dozens of packages but produce zero binaries if none of the packages are main! Linking only links main packages into binaries go build ./... Linking is often the most expensive step in a build because it involves combining all dependencies into a single executable, resolving symbols, and embedding metadata. By keeping linking selective, and relying on cached package compilation, builds remain efficient. What Ends Up in the Binary The final binary is more than just your compiled code. It includes: All dependent packages that are reachable from main Build metadata, including the module version and commit information Machine-level instructions optimized for the target platform All dependent packages that are reachable from main Build metadata, including the module version and commit information Machine-level instructions optimized for the target platform This combination is why Go binaries are self-contained and reproducible: they include everything needed to run without relying on external libraries or runtime environments. From a human perspective, this makes deployment straightforward. From a machine perspective, the build system can verify and cache everything efficiently, ensuring that repeated builds are fast and deterministic. The Build Cache: The Center of Gravity At the heart of Go's speed and predictability is its build cache. Every compiled package, every intermediate artifact, and even some tool outputs are stored in a content-addressed cache, which allows Go to reuse work across builds, commands, and even go run invocations. Understanding how the cache works is essential to grasping why Go builds feel almost instantaneous, even for large projects. build cache go run What the Cache Stores The build cache is more than just compiled binaries. It contains: Compiled package artifacts (.a files) for all packages in the build graph Test results, including cached success information Temporary tool outputs needed for execution by go run or go test Compiled package artifacts (.a files) for all packages in the build graph Test results, including cached success information Temporary tool outputs needed for execution by go run or go test The cache lives on disk (by default in $GOCACHE) and is fully deterministic, meaning the same package compiled with the same inputs will always produce the same cache entry. This ensures that repeated builds, or builds across different machines, produce identical results. $GOCACHE Content-Addressed, Not Timestamp-Based Unlike traditional build systems that rely on file timestamps, Go uses content-based hashing to determine cache keys. Each cache key is a function of: content-based hashing the source code content the compiler version any build flags the target platform (GOOS/GOARCH) relevant environment variables the source code content the compiler version any build flags the target platform (GOOS/GOARCH) GOOS/GOARCH relevant environment variables This design guarantees that builds are reproducible and avoids false cache misses due to innocuous changes like timestamps or file order. Cache Invalidation Explained Even with a robust cache, Go will sometimes recompile packages. Common causes include: Modifying source code or build tags Changing compiler flags or environment variables Renaming files within a package Modifying source code or build tags Changing compiler flags or environment variables Renaming files within a package Go's caching system is smart: it only rebuilds what actually needs rebuilding. Even small, non-semantic changes can trigger recompilation if they affect the package’s build hash, but otherwise, the cache is trusted implicitly. Why the Cache Is Safe to Trust The build cache is designed to be transparent and reliable: You rarely need to manually clear it Rebuilding from scratch produces identical artifacts go run, go test, and go build all leverage it consistently You rarely need to manually clear it Rebuilding from scratch produces identical artifacts go run, go test, and go build all leverage it consistently go run go test go build This is why Go's incremental builds are so fast: the compiler never does more work than necessary. From a developer perspective, it feels magical. From a systems perspective, it's simply an optimized pipeline that treats package artifacts as first-class citizens. go build: Producing Artifacts go build The go build command is the workhorse of the Go toolchain. Its job is simple to describe but sophisticated in execution: compile packages, link them if necessary, and produce a binary that is correct and reproducible. Understanding what go build actually does helps you predict its behavior and avoid common surprises. compile packages, link them if necessary, and produce a binary that is correct and reproducible go build How go build Handles Packages When you run go build on a module or package, the tool first examines the dependency graph derived from your go.mod. Every package in the graph is checked against the build cache: if the cache contains a valid compiled artifact for a package, Go reuses it instead of recompiling. Only packages that have changed - or whose dependencies changed - are rebuilt. go build go.mod Because Go operates at the package level, touching a single file inside a package can trigger a rebuild of the entire package. Conversely, if a dependency hasn't changed, it's never rebuilt, even if other packages rely on it. This per-package granularity is one of the reasons Go's incremental builds scale so well, even for large projects. operates at the package level incremental builds Linking and the Final Binary As we mentioned earlier, go build only produces an executable for main packages. Library packages are compiled into intermediate artifacts but never linked on their own. When linking a main package, Go combines all compiled packages into a single binary. This process also embeds metadata into the executable, including: go build module version information commit hashes (if available) platform-specific build metadata module version information commit hashes (if available) platform-specific build metadata By default, inclusion of version control details is governed by the -buildvcs flag, which defaults to "auto" and stamps VCS information when the repository context allows (use -buildvcs=false to omit or -buildvcs=true to require it). More details can be found in the documentation here. -buildvcs -buildvcs=false -buildvcs=true here This makes Go binaries self-contained and highly reproducible, allowing you to deploy them confidently without worrying about missing dependencies. Where the Artifacts Go (Sorry 😀) By default, go build writes the binary in the current directory, named after the package. If the package is a library, go build doesn't produce a binary at all, it only ensures that the package and its dependencies are compiled. You can control output locations with the -o flag or use ./... to build multiple packages in one go. go build go build -o ./... On Windows, executables have a .exe suffix. When building multiple main packages at once (for example, ./cmd/...) without -o, Go writes one binary per main package into the current directory. .exe ./cmd/... -o Predictable and Reliable Builds The combination of per-package compilation, caching, and selective linking ensures that go build is predictable. You can trust that: builds are reproducible across machines unchanged code is never rebuilt unnecessarily intermediate artifacts are reused to optimize build time builds are reproducible across machines unchanged code is never rebuilt unnecessarily intermediate artifacts are reused to optimize build time In short, go build is not just compiling code, it's orchestrating a deterministic pipeline that balances human convenience with machine efficiency. go build orchestrating a deterministic pipeline that balances human convenience with machine efficiency go run: Convenience Without Special Privileges go run If go build is the workhorse that produces artifacts you can deploy, go run is the fast lane for experimenting and executing code immediately. Many developers think of it as "compiling and running in one step", but it's not: under the hood, it leverages the same build system as go build, it's just optimized for convenience rather than artifact persistence. go build go run go build What go run Actually Does go run When you type go run main.go (or a list of files), Go first evaluates the package and its dependencies just as it would for go build. Any cached compiled packages are reused, so the compiler does minimal work for unchanged code. Then, Go links the main package into a temporary binary, executes it, and deletes the binary once the program finishes. go run main.go go build links the main package into a temporary binary, executes it, and deletes the binary once the program finishes From a caching perspective, go run is not a special path, it fully participates in the build cache. This explains why repeated invocations of the same program often feel instantaneous: the heavy lifting has already been done, and only linking or changed packages may trigger compilation. go run Why go run Feels Different go run Despite sharing the same underlying pipeline, go run can feel slower in certain scenarios. Because it produces a temporary binary every time, linking is repeated, even if all dependencies are cached. For small programs, this overhead is negligible, but for projects with large dependency graphs, it can be noticeable. go run Another difference is that go run does not leave a persistent artifact. This is exactly the point: it trades binary reuse for ease of execution. You don't need to think about where to place the binary or what to call it, the tool handles it automatically. go run does not leave a persistent artifact When go run Is the Right Tool - and When It Isn't go run go run is ideal for: go run quick experiments or scripts running one-off programs without cluttering the filesystem testing small programs interactively quick experiments or scripts running one-off programs without cluttering the filesystem testing small programs interactively It's less suitable for: production builds or deployment long-running servers where repeated linking adds overhead CI pipelines where caching persistent binaries is more efficient production builds or deployment long-running servers where repeated linking adds overhead CI pipelines where caching persistent binaries is more efficient For these cases, the recommended pattern is go build && ./binary, which gives you the benefits of caching, reproducibility, and a persistent artifact without sacrificing performance. go build && ./binary go test and Cached Correctness go test The go test command builds on the same principles as go build and go run, but adds a layer of test-specific caching and execution logic. Understanding how tests interact with the build system helps explain why some tests run instantly while others trigger a rebuild, and why Go's approach feels both fast and predictable. go test go build go run Compilation Reuse in Tests When you run go test, Go first determines the dependency graph for the test package, including any imported packages. Packages that haven't changed are reused from the build cache, just as with go build or go run. This means that large test suites can often start executing almost immediately, because most of the compilation work has already been done. go test reused from the build cache go build go run Even when multiple packages are involved, Go only rebuilds the packages that actually changed. The combination of per-package compilation and caching ensures that incremental test runs are fast, even in large projects. Test Result Caching In addition to caching compiled packages, Go also caches test results. If a test passes and none of its dependencies or relevant flags have changed, Go can skip re-running the test entirely. caches test results Test result caching applies only in package list mode (e.g., go test . or go test ./...). In local directory mode (go test with no package args), caching is disabled. go test . go test ./... go test This behavior is controlled by the -count flag. For example, go test -count=1 forces execution regardless of cached results. (-count repeats tests/benchmarks. -count=1 is the idiomatic way to bypass cached results. See the documentation for further details.) -count go test -count=1 -count -count=1 documentation Caching test results improves developer productivity and CI efficiency, especially for large projects with extensive test coverage. It also reinforces Go's philosophy: the system should avoid unnecessary work while preserving correctness. the system should avoid unnecessary work while preserving correctness Cache Invalidation in Testing A test may be re-run automatically if: The test code itself has changed. Any dependency of the test has changed. Flags affecting the test have changed. Non-cacheable flags or changed files/env also invalidate reuse. The test code itself has changed. Any dependency of the test has changed. Flags affecting the test have changed. Non-cacheable flags or changed files/env also invalidate reuse. Otherwise, Go trusts the cached result, knowing it is deterministic and reproducible. This approach reduces "flaky" builds caused by unnecessary rebuilds and emphasizes predictability over blind convenience. deterministic and reproducible Optional Handy Snippets Here are some useful go test invocations that leverage caching behavior: go test Fresh run: go test -count=1 ./... - as we saw earlier, this disables test result caching. Stress a test: go test -run '^TestFoo$' -count=100 ./pkg - runs TestFoo 100 times to check for flakiness. Bench stability: go test -bench . -count=3 - runs all benchmarks 3 times to get stable measurements. Fresh run: go test -count=1 ./... - as we saw earlier, this disables test result caching. go test -count=1 ./... Stress a test: go test -run '^TestFoo$' -count=100 ./pkg - runs TestFoo 100 times to check for flakiness. go test -run '^TestFoo$' -count=100 ./pkg TestFoo Bench stability: go test -bench . -count=3 - runs all benchmarks 3 times to get stable measurements. go test -bench . -count=3 Why This Matters for Developers From a developer's perspective, the combination of build caching and test result caching creates a workflow that feels instantaneous and reliable: Small changes trigger only the necessary compilation steps. Passing tests rarely run again unless something changes. Developers can iterate rapidly without worrying about hidden state. Small changes trigger only the necessary compilation steps. Passing tests rarely run again unless something changes. Developers can iterate rapidly without worrying about hidden state. By treating both packages and test results as first-class cacheable artifacts, Go makes testing fast and predictable, reinforcing the same "human + machine" optimization that underlies go build and go run. go build go run Observing and Debugging the Build System Most of the time, Go's build system does exactly what you expect, quietly and efficiently. When something feels off, though, the toolchain gives you direct, low-level visibility into what it's doing. The key is knowing which switches to flip and how to interpret what you see. Making the Toolchain Talk Go provides a small set of flags that expose the build pipeline without changing its behavior: -x prints the actual commands executed during the build. This includes compiler invocations, linker steps, and tool executions. It’s the fastest way to answer the question: "What is Go actually doing right now?" -n shows what would be executed, without running the commands. This is useful when you want to understand the build plan without triggering a rebuild. -work preserves the temporary build directory instead of deleting it. This lets you inspect intermediate files, generated code, and temporary artifacts produced during compilation or linking. -x prints the actual commands executed during the build. This includes compiler invocations, linker steps, and tool executions. It’s the fastest way to answer the question: "What is Go actually doing right now?" -x -n shows what would be executed, without running the commands. This is useful when you want to understand the build plan without triggering a rebuild. -n -work preserves the temporary build directory instead of deleting it. This lets you inspect intermediate files, generated code, and temporary artifacts produced during compilation or linking. -work These flags turn the Go toolchain from a black box into a transparent pipeline. Importantly, they don't disable caching, they simply make cache hits and misses visible. Understanding Why a Package Rebuilt One of the most common sources of confusion is a package rebuilding "for no apparent reason". With the right mental model, this becomes easier to diagnose: A package rebuilds when any input to its cache key changes. Inputs include source code, build tags, compiler flags, target platform, and relevant environment variables. Dependency changes propagate upward through the package graph. A package rebuilds when any input to its cache key changes. rebuilds when any input to its cache key changes Inputs include source code, build tags, compiler flags, target platform, and relevant environment variables. Dependency changes propagate upward through the package graph. Using -x, you can often see whether Go reused a cached artifact or recompiled a package, and infer why from the context. This removes the temptation to reach for blunt tools like go clean -cache as a first response. -x go clean -cache Forcing Rebuilds (When You Actually Mean It) Sometimes you really do want to bypass the cache. For example, when validating a clean build or debugging toolchain issues. Go supports this explicitly: -a forces rebuilding of packages, ignoring cached compiled artifacts go clean -cache clears the entire build cache -a forces rebuilding of packages, ignoring cached compiled artifacts -a go clean -cache clears the entire build cache go clean -cache These options are intentionally explicit and slightly inconvenient. Go is designed to make correct reuse the default, and manual cache invalidation the exception. If you find yourself clearing the cache regularly, it's often a sign that something else in the build setup needs attention. Avoiding Superstition-Driven Fixes Because Go's build system is deterministic, guessing rarely helps. Flags like -x, -n, and -work give you concrete evidence of what's happening, which is almost always enough to explain surprising behavior. -x -n -work Once you trust that: builds are content-addressed, packages are the unit of work, and the cache is safe to reuse, builds are content-addressed, packages are the unit of work, and the cache is safe to reuse, debugging build behavior becomes a matter of observation rather than trial and error. Implications for Real Projects The design choices behind Go's build system aren't accidental. They show up most clearly once you move beyond small examples and start working on real codebases: continuous integration pipelines, large repositories, and editor-driven workflows. The same principles that make go build feel fast locally are what make Go scale so well in production environments. go build CI Pipelines and Reproducibility Go's emphasis on deterministic, content-addressed builds makes it particularly well-suited for CI. Because build outputs are derived entirely from source content, module versions, and explicit configuration, CI builds behave consistently across machines and environments. There's no reliance on filesystem timestamps, hidden state, or global configuration. This predictability also makes Go builds highly cache-friendly. Whether you're using a shared build cache, container layers, or remote caching infrastructure, Go's package-level compilation model fits naturally. When a build is slow in CI, it's usually because something actually changed, not because the system decided to do extra work. Monorepos and Large Codebases In large repositories, the build cache becomes a performance boundary. Because Go caches compiled packages independently, small, well-defined packages can be reused across many builds with minimal overhead. This encourages a code structure where dependencies are explicit and packages remain focused. The flip side is that overly large or tightly coupled packages can become bottlenecks. A small change in a heavily used package can invalidate a large portion of the cache, increasing build times across the entire repository. Go doesn't hide this cost though, it makes package boundaries visible and meaningful, rewarding good structure and exposing poor separation early. Editors, Tooling, and Automation The same build model powers Go's tooling ecosystem. Code editors, language servers, linters, and code generators all rely on the same package-level understanding of your code. Because the toolchain exposes a clear, deterministic build pipeline, tools can integrate deeply without guessing or reimplementing build logic. This is one reason Go tooling feels unusually consistent: editors and CI systems see your code the same way the compiler does. From autocomplete to refactoring to automated testing, everything builds on the same assumptions about packages, dependencies, and caching. Conclusion: Trust the Model Go's build system succeeds because it makes a clear trade-off: it optimizes for predictability over cleverness, and for explicit structure over implicit behavior. At the surface, this looks like simplicity. Underneath, it's a carefully engineered pipeline that treats packages as the unit of work, content as the source of truth, and caching as a correctness feature rather than a performance hack. Once you internalize this model, many everyday behaviors start to make sense. Builds are fast not because Go is doing less work, but because it avoids doing unnecessary work. go run feels convenient because it reuses the same machinery as go build, not because it shortcuts correctness. Test execution is reliable because test results are cached using the same deterministic rules as compiled packages. unnecessary go run go build For humans, this means fewer surprises, faster feedback loops, and tooling that behaves consistently across code editors, machines, and CI systems. For machines, it means reproducible builds, cache-friendly artifacts, and a system that scales naturally as codebases grow. The same design choices serve both audiences. If there's one takeaway, it's this: Go's build system isn't something to fight or work around. It's an API in its own right - one that rewards understanding. Once you trust the model, the toolchain stops feeling magical and starts feeling dependable, which is exactly what you want from the infrastructure that builds your code.