nix-build.2

Build a Nix expression

$ nix-build '<nixpkgs>' [[-A|--attr]] [firefox]

$ nix-build '<nixpkgs>' [[-A|--attr]] [firefox] --option sandbox true

nix-build [path_to_nix_expression] [options...]

--attr
    Build the specified attribute from a Nix expression (e.g., pkgs.hello from a flake or default.nix). Supports multiple --attr flags.

--expr
    Build the given Nix expression string directly, without needing a file. For example: nix-build --expr 'with import {}; hello'.

--file
    Build the expression found in the specified Nix file (default is default.nix or a flake in the current directory).

--no-out-link
    Do not create a symlink named result in the current directory pointing to the build output.

--out-link
    Create a symlink named path (instead of result) to the build result in the current directory.

--arg
    Pass a value for a top-level argument to the Nix expression being built. The value is interpreted as a Nix expression.

--argstr
    Pass a string value for a top-level argument to the Nix expression. The value is passed as a literal string.

--dry-run
    Evaluate the expression and determine what would be built, but do not perform any actual builds or store operations.

--json
    Output build information and results in JSON format, suitable for machine parsing.

--keep-failed
    Do not delete the temporary build directory if the build fails. Useful for debugging build failures.

--keep-going
    Continue building other derivations even if one or more derivations fail.

--max-jobs
    Allow at most N jobs to run in parallel. A value of 0 means infinite jobs (limited by CPU cores).

--cores
    Set the maximum number of CPU cores to use for local builds. A value of 0 means all available cores.

--show-trace
    Show evaluation stack traces when an error occurs during Nix expression evaluation, providing more context for debugging.

--no-allow-substitutes
    Disable fetching pre-built binaries (substitutes) from configured binary caches. Forces local builds.

--fallback
    Allow falling back to building locally if fetching a substitute from a binary cache fails.

--rebuild
    Force rebuilding of a derivation, even if it already exists in the Nix store and is valid.

--system
    Specify the system architecture for which to build (e.g., x86_64-linux, aarch64-darwin).

--verbose
    Set the verbosity level for logging messages. Higher levels provide more detailed output.

nix-build is a fundamental command in the Nix ecosystem. It evaluates a Nix expression, which typically defines a software package or a set of packages, and then orchestrates its build. The building process involves fetching source code, applying patches, compiling, and installing components into the isolated Nix store. A key feature of Nix builds is their isolation and reproducibility: each build runs in a clean environment, ensuring only declared inputs are available.

Upon successful completion, nix-build creates a symlink named result (by default) in the current directory, pointing to the built output in the Nix store. This provides easy access to the artifact. It also leverages Nix's caching mechanism, meaning if an identical package has been built before (locally or available via a binary cache), it won't be rebuilt, significantly speeding up development.

Builds can be resource-intensive, consuming significant CPU, memory, and disk space.
Network access is often required for fetching source code and pre-built binaries (substitutes).
Reproducibility can be compromised if impure inputs are used (e.g., through --impure or by not using flakes effectively).

By default, nix-build creates a symlink named result in the current directory, pointing to the built derivation in the Nix store. This symlink provides a convenient way to access the built artifact for testing or further processing. This behavior can be controlled with the --no-out-link or --out-link options.

nix-build leverages Nix's core principles of reproducibility and isolation. Builds occur in a sandboxed environment where only explicitly declared inputs are available, ensuring consistent and reproducible results across different machines and times.

Nix automatically caches build results. If a derivation with identical inputs has been built before (locally or is available from a configured binary cache), nix-build will retrieve the cached output instead of rebuilding, significantly speeding up development and deployment workflows.

nix-build belongs to the 'legacy' Nix CLI. For modern Nix workflows and a unified command-line experience, consider using the nix build command (e.g., nix build .#myPackage for flakes) which offers similar functionality with an updated interface and often better integration with new Nix features.

nix-build is part of the original, 'legacy' Nix command-line interface. It has been a cornerstone of the Nix package manager since its early days, providing the fundamental mechanism for building packages and creating symlinks to their outputs. With the introduction of the unified nix command (often referred to as the 'new' Nix CLI) around Nix 2.0, its functionality has largely been absorbed and extended by nix build and nix develop. While still fully functional and widely used, especially in older scripts or workflows, new Nix projects typically favor the modern nix command for a more consistent user experience.

nix-shell(1), nix-instantiate(1), nix-store(1), nix(1)