Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

Go build constraints

Reference for Go build constraints: //go:build expressions, &&, || and !, GOOS and GOARCH file name suffixes, built-in tags like unix and cgo, and custom tags.

A build constraint (also called a build tag) tells the go command to include a file in a build only under certain conditions: on one operating system, with a custom tag, or from a certain Go version on. It lets one package hold platform-specific code or optional features without any preprocessor.

There are two ways to write a constraint. A //go:build line at the top of the file holds a boolean expression, and a file name ending in _GOOS, _GOARCH or both (such as files_linux.go or io_windows_amd64.go) works as an implicit constraint. A file that is excluded is not compiled, and not even parsed beyond the header, so it may contain code that would not build on the current platform.

Go
//go:build linux && (amd64 || arm64)

package sys

Try it

Go A file that is included only on some systems

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Evaluating constraint expressions with go/build/constraint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
//go:build expression

The expression uses tags and these operators, from lowest to highest precedence: ||, &&, !. Parentheses group. A tag is an identifier made of letters, digits, _ and ..

Placement rules:

Rule Description
Position Before the package clause, preceded only by blank lines and other line comments.
Blank line A blank line must separate the constraint from the package clause (otherwise it would become the package doc comment).
One per file Only one //go:build line is allowed. Put alternatives in the expression with `
Comment form It must be a line comment starting with //go:build, with no space after the slashes. A /* */ comment is not a constraint.

Tags that are set automatically:

Tag Meaning
GOOS and GOARCH values linux, windows, darwin, amd64, arm64, and so on. android also satisfies linux, and ios also satisfies darwin.
unix True for every Unix-like GOOS (Go 1.19).
gc, gccgo The compiler in use.
cgo cgo is enabled.
go1.N True when the toolchain's language version is at least 1.N.
race, msan, asan The matching sanitizer is on.
goexperiment.name A GOEXPERIMENT is enabled.
Tags from -tags Whatever you pass: go build -tags=integration,postgres.

File name rules. The suffix forms *_GOOS.go, *_GOARCH.go and *_GOOS_GOARCH.go apply only when the word is a known OS or architecture name. _test.go marks test files. Files beginning with _ or . are ignored entirely.

Errors and edge cases: when every file in a directory is excluded the command stops with build constraints exclude all Go files. A malformed expression is reported by the go command (and by go vet) with the file and line.

Usage notes

  • Pairs of files for two implementations. Write clock_unix.go with //go:build unix and clock_windows.go that exposes the same function names. Add a fallback file (//go:build !unix && !windows) so other systems still compile.
  • Opt-in tests. Put slow tests behind //go:build integration and run them with go test -tags=integration ./....
  • //go:build ignore. The word ignore is not special to the go tool; it is just a tag nobody sets. It is the usual way to keep a generator script in a package directory without building it. Run it with go run gen.go.
  • Version gating. //go:build go1.22 on a file selects it for new toolchains. In a module, a constraint using go1.N also sets the language version for that file, which is how a file can use an older loop-variable meaning (see Loop variable semantics).
  • Old // +build lines. Before Go 1.17 constraints were written // +build linux,amd64. New code uses only //go:build; gofmt converts old lines and go vet checks that both agree if both are present.
  • Do not overuse. Many tags multiply the combinations you need to test. Prefer runtime checks (runtime.GOOS) for small differences that compile everywhere.
  • See what is selected. go list -f '{{.GoFiles}} {{.IgnoredGoFiles}}' . shows which files were used and which were excluded.