Build tags let the compiler pick the right file
You are building a file watcher. On Linux, you tap into inotify to get instant notifications when a file changes. On Windows, inotify does not exist. You need ReadDirectoryChangesW. You could sprinkle if runtime.GOOS == "linux" checks throughout your code, but that clutters every function with branching logic. You want the compiler to include only the code that works on the target machine. Build tags solve this. They act as compile-time switches that tell the toolchain exactly which files belong in the final binary.
Think of a build tag like a label on a shipping manifest. The compiler reads the label before it opens the box. If the destination matches the label, the package gets loaded onto the truck. If it does not match, the package stays in the warehouse. The binary never sees it. There is no runtime overhead. Excluded files do not bloat your executable. Their types, functions, and variables simply do not exist in the compiled package. This keeps your codebase clean and your binaries lean.
Minimal example
Here is the simplest build tag in action. A single file that only compiles on macOS.
//go:build darwin
// +build darwin
package main
// SayHello prints a message specific to macOS.
func SayHello() {
// This function only exists when building for darwin.
// On other systems, this file is invisible to the compiler.
// The binary size shrinks because dead code is stripped early.
println("Hello from macOS")
}
The //go:build darwin line restricts compilation to macOS targets. The // +build darwin line is a legacy fallback for Go versions before 1.17. The package main declaration must follow the build tag block immediately. If you insert a blank line between the tag and the package declaration, the compiler ignores the tag. The file compiles on every platform, which usually breaks your build with duplicate symbols.
Position matters more than syntax. Keep the tag at the very top.
Walkthrough of the build process
When you run go build, the compiler scans every file in the package directory. It looks for the //go:build comment inside the first comment block. If the comment exists, the compiler evaluates the expression against the build target. The target includes the operating system, architecture, and any custom tags you pass to the toolchain.
Suppose you are building for Linux. The compiler sees //go:build darwin. It checks the target OS. The target is linux, not darwin. The expression evaluates to false. The compiler skips the file entirely. It never parses the rest of the file. Syntax errors inside the file do not matter. The file is dead code until the tag matches.
If you build for macOS, the expression evaluates to true. The compiler includes the file. It parses the code, checks types, and generates machine code. The SayHello function becomes part of the binary.
Build tags support standard boolean operators. && means AND. || means OR. ! means NOT. You can group expressions with parentheses. //go:build linux && amd64 includes the file only on Linux with 64-bit x86 architecture. //go:build !windows includes the file on every platform except Windows. You can nest groups freely: //go:build (linux || darwin) && amd64.
The compiler evaluates tags before type checking. False tags hide syntax errors.
Realistic example
Real code often needs platform-specific implementations that share the same API. A common pattern is to split a package into multiple files, one per platform. Each file defines the same functions but with different logic. The compiler assembles the package by picking the file that matches the target.
Here is a sys package that returns the hostname. The Linux implementation reads a virtual filesystem path.
//go:build linux
// +build linux
package sys
import "os"
// GetHostname returns the hostname using Linux-specific calls.
func GetHostname() string {
// Reading /proc avoids expensive syscall overhead.
// The virtual filesystem is guaranteed to exist on Linux.
// We trim whitespace because the file includes a newline.
b, _ := os.ReadFile("/proc/sys/kernel/hostname")
return string(b)
}
Here is the Windows counterpart in the same directory.
//go:build windows
// +build windows
package sys
import "os"
// GetHostname returns the hostname using Windows environment variables.
func GetHostname() string {
// Windows does not expose /proc. Environment variables are reliable.
// We fall back to an empty string if the variable is missing.
// This avoids panics on restricted or containerized setups.
return os.Getenv("COMPUTERNAME")
}
Both files live in the same directory. They share the same package name. They define the same function signature. When you build for Linux, the compiler includes the first file and skips the second. The sys package exports GetHostname with the Linux implementation. When you build for Windows, the compiler includes the second file and skips the first. The API stays the same. The caller does not need to know which file was used.
Split by platform, not by feature. Keep the public interface identical.
Custom tags and testing
Build tags are not limited to OS and architecture. You can define your own tags and pass them to the compiler. This is useful for toggling features, enabling debug mode, or running integration tests.
To use a custom tag, add it to the file and pass -tags to go build or go test.
//go:build debug
// +build debug
package logger
// LogDebug prints debug messages when the debug tag is active.
func LogDebug(msg string) {
// This function is compiled only when -tags debug is passed.
// In production builds, this file is excluded entirely.
// The binary stays small and logging overhead disappears.
println("[DEBUG]", msg)
}
When you run go build -tags debug, the compiler includes the file. The LogDebug function exists. When you run go build without the tag, the compiler excludes the file. The function disappears. If your code calls LogDebug without the tag, the compiler rejects the program with an undefined: logger.LogDebug error. This forces you to keep debug code isolated.
Custom tags are essential for integration tests. You might have tests that require a database or a network connection. You do not want these tests to run during a quick go test. You can tag them with //go:build integration.
//go:build integration
// +build integration
package db_test
import "testing"
// TestConnect verifies the database connection works.
func TestConnect(t *testing.T) {
// This test runs only when -tags integration is passed.
// It skips during normal test runs to keep CI fast.
// We assume a running database is available in the test env.
conn := connectToDB()
if conn == nil {
t.Fatal("connection failed")
}
}
Run go test -tags integration to execute these tests. Run go test to skip them. This lets you separate fast unit tests from slower integration tests.
Tags gate functionality at compile time. Use them to keep production binaries clean.
Pitfalls and errors
Build tags are easy to mess up. The most common mistake is a blank line. The build tag must be in the first comment block. If you put a blank line before the tag, the compiler treats the file as having no constraints. The file compiles on every platform. If you intended exclusivity, you now have duplicate symbols. The compiler screams with redeclared in this block. Check the top of the file first when tags behave strangely.
Another pitfall is overlapping tags. If two files in the same package match the same build target, the compiler includes both. If they define the same function, you get a redeclaration error. Make sure your tags are mutually exclusive. Use ! to exclude platforms explicitly if needed.
Build tags also interact with init(). If a tagged file contains an init() function, that function runs only when the tag matches. If you rely on init() to set up global state, make sure the tag is active. Otherwise, the initialization is skipped. The program might crash later with a nil pointer or missing configuration.
The compiler does not warn you if a file is excluded. It just skips it. If you misspell a tag or use the wrong OS name, the file vanishes silently. The error will appear where you use the function, not where the file is. The compiler complains with undefined: pkg.FuncName. Trace the error back to the source file and check the tag.
Convention aside: gofmt preserves build tags. It does not reorder them or change their syntax. Trust the formatter. Do not manually tweak the tag block. If you need to change the tag, edit the comment and run gofmt. The tool keeps the block valid. Go also kept the legacy // +build syntax purely for backward compatibility. New code should only use //go:build, but keeping both lines side by side is harmless and widely accepted in the community.
Silent exclusion is the quietest bug. Verify your tags match your target.
When to use build tags
Use build tags when you need platform-specific implementations that share the same API. Use build tags when you want to exclude test helpers or debug code from production binaries. Use build tags when a dependency is only available on certain systems. Use runtime checks like runtime.GOOS when the difference is minor and can be handled in a single file. Use environment variables when the behavior changes per deployment, not per compilation.
Compile-time switches keep binaries lean. Runtime checks keep logic flexible. Pick the boundary that matches your problem.