The file that only exists in certain worlds
You are writing a network utility that needs to open a raw socket on Linux, but on macOS it has to fall back to a standard TCP listener. On Windows, the entire feature is disabled. You could write a giant if runtime.GOOS == "linux" block inside your main function, but that clutters the happy path with platform checks and forces the compiler to include dead code in every binary. Go gives you a cleaner escape hatch: the compiler can completely ignore a file before it even tries to parse the code inside it. Build tags let you split your codebase into environment-specific islands without polluting the shared logic.
How the compiler evaluates constraints
Think of build constraints like a bouncer at a club door. The compiler walks through your directory, picks up every .go file, and asks the bouncer for permission. If the file passes the check, the compiler reads it, type-checks it, and links it into the binary. If it fails, the file is treated as if it does not exist. The code inside never runs, never compiles, and never contributes to the final executable size. This is fundamentally different from runtime conditionals. Runtime checks keep the code in the binary and evaluate it every time the program starts. Build constraints remove the code at compile time.
The evaluation happens in a strict sequence. The Go toolchain scans the directory for .go files. For each file, it reads the first few lines looking for a //go:build directive. If it finds one, it parses the boolean expression and evaluates it against the current build environment. The environment includes the target operating system, the target architecture, the Go version, and any custom tags passed via the -tags flag. If the expression resolves to true, the file enters the parsing phase. If it resolves to false, the file is discarded immediately. This early exit means you can safely put platform-specific imports inside the constrained file without triggering imported and not used errors on other platforms. The compiler never sees those imports.
Go convention dictates that you should never fight the formatter. gofmt ignores build constraint comments and leaves them exactly where you place them. Most editors run gofmt on save, so your constraint headers will stay aligned and consistent across the team. Trust the tool. Argue logic, not formatting.
The modern syntax and boolean logic
Here is the simplest way to restrict a file to a single operating system. The constraint lives at the very top of the file, before the package declaration.
//go:build linux
package main
// Init runs only when the compiler targets Linux.
func init() {
// Linux-specific setup goes here
}
The //go:build directive tells the Go toolchain to include this file only when the target OS matches linux. If you run go build on a Mac, the compiler skips this file entirely. The init function never gets linked. The rest of your package compiles normally.
Real projects rarely rely on a single tag. You usually need to combine OS, architecture, and custom flags. Here is a production-style setup that handles a database driver selection based on the target environment.
//go:build linux && amd64 && !no_driver
package storage
import "database/sql"
// RegisterDriver loads the optimized Linux binary driver.
func RegisterDriver() {
// Only linked when all three constraints match
sql.Register("postgres", &optimizedDriver{})
}
The !no_driver part demonstrates how custom tags work. You pass custom constraints through the -tags flag when building: go build -tags no_driver. The compiler treats no_driver as a boolean variable that defaults to false. Adding the negation operator flips the logic, so the file is excluded only when you explicitly request it. This pattern is common for optional features, experimental code, or stripping debug logging before release.
Go convention dictates that custom tags should be lowercase and descriptive. Avoid single letters. The community also expects you to document custom tags in your README or package documentation. If a contributor runs go build without knowing about -tags experimental, they will get a linker error for missing symbols. Make the contract explicit. Public names start with a capital letter, private names start lowercase, and build tags follow the same casing rules. Keep them consistent.
Filename suffixes and directory layout
You do not always need a comment at the top of the file. Go supports implicit constraints through filename suffixes. A file named config_darwin.go automatically applies the darwin constraint. A file named config_windows_386.go applies both windows and 386. The compiler splits the filename on underscores, checks the suffix against known OS and architecture names, and applies the constraint if it matches. This keeps your directory clean and makes platform-specific files obvious at a glance.
You will occasionally see older codebases using // +build linux,amd64. That is the legacy syntax from Go 1.4 and earlier. The comma means AND, and spaces mean OR. It works, but it is harder to read and does not support parentheses. The modern //go:build syntax replaced it in Go 1.17. If you maintain a file that needs to support both old and new toolchains, you can stack them:
//go:build linux && amd64
// +build linux,amd64
package main
// Main entry point for constrained builds.
func main() {
// Legacy dual-header setup
}
The new toolchain reads the first comment and ignores the second. The old toolchain skips the first comment and reads the second. You only need this dual-header if you are supporting Go versions older than 1.17. Most projects have moved past that threshold. The underscore discard operator _ is sometimes used inside constrained files to intentionally ignore return values from platform-specific APIs, signaling to reviewers that the omission is deliberate. Use it sparingly with errors, but freely with unused struct fields or channel receives.
Realistic package split
Large codebases benefit from splitting platform logic into separate files rather than scattering if statements across a single monolith. Here is how a realistic package layout looks when you separate shared logic from platform-specific implementations.
// driver.go
package storage
// Driver defines the interface all platforms must implement.
type Driver interface {
Connect() error
Close() error
}
// New returns the appropriate driver for the current build target.
func New() Driver {
// Defer selection to the constrained init functions
return defaultDriver
}
The shared file defines the contract. It does not care about OS or architecture. It only cares that something implements Driver. Go convention favors accepting interfaces and returning structs. The constrained files will return concrete structs that satisfy this interface.
// driver_linux.go
//go:build linux
package storage
import "os"
// linuxDriver implements Driver for Linux environments.
type linuxDriver struct {
socketPath string
}
func init() {
// Register the Linux implementation at package initialization
defaultDriver = &linuxDriver{socketPath: "/var/run/app.sock"}
}
// Connect opens the Unix domain socket.
func (d *linuxDriver) Connect() error {
// Linux-specific socket logic
return os.Open(d.socketPath)
}
// Close releases the socket handle.
func (d *linuxDriver) Close() error {
return nil
}
The constrained file implements the interface and registers itself during init. The receiver name d follows the convention of using one or two letters matching the type. You do not need this or self. The compiler links exactly one implementation into the final binary. If you forget to provide a fallback for an unsupported platform, the linker will complain with undefined: defaultDriver. That error saves you from shipping a binary that panics on startup.
When constraints bite back
Build constraints are powerful, but they introduce subtle failure modes. The most common mistake is placing the constraint comment after the package declaration or after an import block. The compiler requires the //go:build directive to be the very first comment in the file, optionally preceded only by blank lines. If you put it anywhere else, the compiler treats it as a regular comment and compiles the file unconditionally. You will likely hit a runtime panic or a missing-symbol linker error when the platform-specific code executes on the wrong machine.
Another trap involves the testing package. Test files ending in _test.go are excluded from normal builds. If you add a build constraint to a test file, you must remember that the constraint applies to both go build and go test. A file named helper_linux_test.go will only run during tests on Linux. If you forget the OS suffix and only use //go:build linux, the test runner might still pick it up on other platforms if the constraint evaluation order clashes with the test file naming convention. Keep test constraints explicit.
The compiler will not warn you if a constraint excludes every file in a package. You will get a build constraints exclude all Go files in /path/to/pkg error. This usually means you mistyped an OS name, used the wrong architecture tag, or accidentally negated a condition. Double-check your boolean logic. The Go toolchain is strict about tag names. linux works. Linux does not. amd64 works. x86_64 does not. Use the exact strings that go tool dist list outputs.
Goroutine leaks happen when the goroutine waits on a channel that never gets closed. Always have a cancellation path. The same principle applies to constrained initialization. If your init function starts a background goroutine, make sure that goroutine respects context.Context cancellation. Context is plumbing. Run it through every long-lived call site. A constrained file that spawns a daemon without a shutdown hook will hang your program on platforms where that file is active.
Picking your constraint strategy
Use a //go:build comment when you need complex boolean logic or custom tags that do not map to OS or architecture names. Use a filename suffix like _linux.go when you want platform-specific files to be visually obvious in your directory listing. Use the -tags flag when you need to toggle optional features, debug modes, or third-party driver selections without changing source code. Use runtime conditionals like runtime.GOOS when the difference is minor and keeping the code in a single file improves readability. Use separate packages for large platform divergences instead of scattering constraints across dozens of files. Use context propagation when constrained initialization spawns background work.
Constraints are compile-time switches, not runtime features. Keep them simple, document them, and let the compiler do the heavy lifting.