All commands are subcommands of go2nix. Set GO2NIX_DEBUG=1 for verbose
output.
Generate a lockfile from one or more Go module directories.
go2nix generate [flags] [dir...]
| Flag | Default | Description |
|---|---|---|
-o |
go2nix.toml |
Output lockfile path |
-j |
NumCPU |
Max parallel hash invocations |
When no directory is given, defaults to .. Multiple directories produce a
merged lockfile (monorepo support).
The generated lockfile is shared by both builder modes. Use
buildGoApplication (default) or buildGoApplicationExperimental in Nix.
Examples:
go2nix generate . # write go2nix.toml in the current module
go2nix # same — a completely bare invocation runs generate
go2nix generate -o lock.toml ./a ./b # merged lockfile for two modulesgenerate reads each directory's go.mod (its require and replace
lines, so tidy it first) and downloads every module to hash it: it needs
go on PATH and access to your GOPROXY. An existing output file is used
as a cache, so a re-run only downloads what changed. -o is relative to the
current directory, not to dir. Only the bare go2nix defaults to
generate; go2nix ./dir or go2nix -o x.toml is an unknown command, and
there is no top-level --help (each subcommand has -h).
See Lockfile Format for the output schema.
Validate a lockfile against go.mod.
go2nix check [flags] [dir]
| Flag | Default | Description |
|---|---|---|
--lockfile |
go2nix.toml |
Path to lockfile for consistency check |
Verifies that every go.mod requirement (filesystem replaces aside) has a
path@version entry in the lockfile's [mod]. It does not recompute hashes,
look at [replace], or complain about entries that are no longer needed.
It prints nothing and exits 0 on success; on failure it exits 1 with
check failed and the missing modules. Notes: flags go before dir
(go2nix check --lockfile x.toml dir), only one directory is taken, the
default --lockfile is relative to the current directory, and a lockfile
that does not exist reads as an empty one, so every module is reported
missing.
compile-package, link-binary and test-packages are what the default
mode's derivations run; resolve is what the experimental mode's wrapper
runs (and it calls compile-package from the derivations it registers). You
won't normally run these; they are documented for debugging build failures.
The manifests they read are JSON files the Nix side writes into the build
directory.
Compile a single Go package to an archive (.a file). Every per-package
derivation runs it, in both modes: directly from the raw builder for pure-Go
packages, through the compile-go-pkg.sh hook for cgo ones, and from the
derivations go2nix resolve registers in experimental mode.
go2nix compile-package --manifest FILE --import-path PATH --src-dir DIR --output FILE [flags]
| Flag | Required | Description |
|---|---|---|
--manifest |
Yes | Path to compile-manifest.json |
--import-path |
Yes | Go import path for the package |
--src-dir |
Yes | Directory containing source files |
--output |
Yes | Output .a archive path |
--iface-output |
No | Write export-data-only interface (.x) to this path; --output then receives the link object via -linkobj |
--importcfg-output |
No | Write importcfg entry for consumers to this path |
--trim-path |
No | Path prefix to trim (default: $NIX_BUILD_TOP) |
--p |
No | Override -p flag (default: import-path) |
--go-version |
No | Go language version for -lang (default: read from go.mod) |
--module-path |
No | Owning module's path; with --module-version, source paths are rewritten to <module>@<version>/... as go build -trimpath does |
--module-version |
No | Owning module's version (from the require line); empty for main-module packages, which rewrite to the import path |
Link Go application binaries. Reads a link manifest that declares all inputs (importcfg parts, local archives, ldflags, etc.), validates the lockfile, generates modinfo, compiles main packages, and invokes the linker. Used internally by the default mode's build phase.
go2nix link-binary --manifest FILE --output DIR
| Flag | Required | Description |
|---|---|---|
--manifest |
Yes | Path to link-manifest.json |
--output |
Yes | Output directory (binaries written to <output>/bin/) |
Compile and run the tests of the local packages that are part of the build. Used internally by the default mode's check phase.
go2nix test-packages --manifest FILE
| Flag | Required | Description |
|---|---|---|
--manifest |
Yes | Path to test-manifest.json |
Discovers local packages with _test.go files, keeps those whose archive is
in the manifest (the subPackages closure plus test-only helpers; the rest
are skipped), compiles internal and external test archives, generates test mains, links test binaries, and
runs them. See test-support.md for details on the
test pipeline.
Build-time command for experimental mode (the nix/dynamic/ builder).
Discovers the package graph, computes CA .drv paths in-process, registers
them with the nix-daemon (falling back to nix derivation add if no daemon
socket is reachable), and produces a .drv file as output. See
Experimental Mode.
go2nix resolve [flags]
| Flag | Required | Description |
|---|---|---|
--src |
Yes | Store path to Go source |
--mod-root |
No | Subdirectory within src containing go.mod |
--lockfile |
Yes | Path to go2nix.toml lockfile |
--system |
Yes | Nix system (e.g., x86_64-linux) |
--go |
Yes | Path to go binary |
--nix |
Yes | Path to nix binary |
--pname |
Yes | Output binary name |
--output |
Yes | $out path |
--stdlib |
Yes | Path to pre-compiled Go stdlib |
--go2nix |
No | Path to go2nix binary (defaults to self) |
--bash |
No | Path to bash binary |
--coreutils |
No | Path to a coreutils binary (e.g., coreutils/bin/mkdir) |
--sub-packages |
No | Comma-separated sub-packages |
--tags |
No | Comma-separated build tags |
--ldflags |
No | Linker flags |
--cgo-enabled |
No | Override CGO_ENABLED (0 or 1) |
--gcflags |
No | Extra flags for go tool compile |
--pgo-profile |
No | Store path to pprof CPU profile for PGO |
--overrides |
No | JSON-encoded packageOverrides |
--cacert |
No | Path to CA certificate bundle |
--netrc-file |
No | Path to .netrc for private modules |
--nix-jobs |
No | Max concurrent derivation registrations |
--daemon-socket |
No | nix-daemon Unix socket; default $NIX_DAEMON_SOCKET_PATH. When reachable, derivations are registered over the socket instead of via nix CLI subprocesses |
This command is not intended for direct use — it is invoked by the experimental-mode Nix builder inside a recursive-nix build.
Not called by anything. They show what the builders see: which files go
would pick in a directory, which packages a module has, what build
information a binary would embed, what a generated test main looks like.
List Go source files for a package directory, respecting build tags and constraints.
go2nix list-files [-tags=...] [-go-version=...] <package-dir>
Outputs JSON with categorized file lists (Go files, C files, assembly, etc.).
-go-version sets the target Go toolchain version (e.g. 1.25) used to
evaluate //go:build go1.N constraints; defaults to go env GOVERSION.
List all local packages in a Go module with their import dependencies.
go2nix list-packages [-tags=...] [-go-version=...] <module-root>
Outputs JSON with each package's import path and dependencies.
Generate a modinfo linker directive for embedding debug/buildinfo
metadata into the final binary. This is a standalone utility; the default
mode's link-binary command generates modinfo internally.
go2nix build-modinfo [flags] <module-root>
| Flag | Required | Description |
|---|---|---|
--lockfile |
Yes | Path to go2nix.toml lockfile |
--go |
No | Path to go binary (default: from PATH) |
--main-path |
No | Import path of the main package (default: the module path) |
--main-dir |
No | Directory of the main package, read for //go:debug directives (default: MODULE_ROOT) |
Outputs a modinfo directive for the linker's importcfg (embedding
debug/buildinfo metadata), and optionally a godebug line with the
default GODEBUG value parsed from the module's go.mod (used for
-X=runtime.godebugDefault=...).
Generate a _testmain.go file that registers test, benchmark, fuzz, and
example functions. Standalone: the test runner generates its mains in-process
with the same code, nothing calls this subcommand.
go2nix generate-test-main [flags]
| Flag | Required | Description |
|---|---|---|
--import-path |
Yes | Import path of the package under test |
--module-path |
No | Module path of the main module |
--test-files |
No | Comma-separated absolute paths to internal _test.go files |
--xtest-files |
No | Comma-separated absolute paths to external _test.go files |
--output |
No | Output file path (default: stdout) |