nix-build

View documentation for the traditional builder

$ tldr nix-build.2

$ tldr nix build.3

nix-build [PATH...] [OPTIONS...]

--attr , -A
    Selects a specific attribute from the top-level Nix expression to build. Useful for building specific components from a large Nix file.

--expr , -E
    Interprets arguments as Nix expressions rather than file paths. Allows building a derivation defined directly on the command line.

--out-link , -o
    Specifies the name of the symbolic link created in the current directory, defaulting to `result`. Use `--no-out-link` to prevent creating one.

--max-jobs , -j
    Limits the maximum number of parallel build jobs. `auto` uses the number of CPU cores; `0` means unlimited.

--show-trace
    Shows a full stack trace in case of evaluation errors within the Nix expression, aiding debugging.

--arg , --argstr
    Passes arguments to the Nix expression. `--arg ` passes a Nix value (e.g., a list), while `--argstr ` passes a string value.

--keep-failed
    Prevents the deletion of temporary build directories for failed builds, allowing inspection of the build environment and logs.

--keep-going
    Continues building other derivations even if some dependencies or independent derivations fail. The command will still exit with a non-zero status if any build failed.

--json
    Emits structured JSON output instead of human-readable logs for build events, useful for scripting and integration.

--dry-run
    Shows what would be built without actually performing the build. This can be useful for planning and debugging dependencies.

--verbose
    Increases the verbosity of logging output, providing more detailed information about the build process.

The nix-build command is a fundamental tool within the Nix ecosystem, primarily used to build Nix derivations. A derivation is a specification of a build process, including its inputs, outputs, and build script. nix-build takes one or more Nix expressions (typically `.nix` files) or attributes from a Nix expression as input, which ultimately evaluate to derivations.

Upon execution, nix-build first instantiates the Nix expression into a concrete derivation in the Nix store. Then, it realizes this derivation by executing the specified build actions. It automatically handles dependencies, fetching or building them as needed, ensuring that builds are isolated, reproducible, and atomic. If a build is successful, nix-build creates a symbolic link in the current directory (typically `result`) pointing to the build output in the Nix store. This command is the primary way to compile, package, and install software using Nix.

Disk Space Consumption: Nix stores all build inputs and outputs in the Nix store, which can consume significant disk space over time. Regular garbage collection (`nix-collect-garbage`) is essential to reclaim space.
Build Times: For complex software or when starting with a new Nix installation, initial builds can be lengthy as all dependencies might need to be downloaded or compiled from scratch.
Purity Requirements: Builds are expected to be pure. Relying on external factors like unmanaged filesystems or network access (outside of `fetch*` functions) can lead to non-reproducible results. Debugging impure builds can be challenging.
Nix Language Learning Curve: Effectively using `nix-build` and extending its capabilities often requires a solid understanding of the Nix language and its core concepts (derivations, attributes, builtins, etc.).

When you run nix-build, it primarily performs two main stages:
1. Instantiation: The Nix expression (e.g., your `default.nix` file) is evaluated to produce a derivation, which is a low-level, abstract description of a build. This phase generates a `.drv` file in the Nix store.
2. Realization: The derivation is then executed. This involves fetching source code, applying patches, compiling, and installing, with all dependencies automatically managed by Nix. The output of this phase is stored in the Nix store, identified by a unique hash.

By default, upon a successful build, nix-build creates a symbolic link named `result` in the current directory. This link points directly to the output path of the built derivation in the Nix store (e.g., `/nix/store/hash-name-package`). This `result` symlink is a convenient and common way to access the built artifacts without needing to know their specific hash in the store.

nix-build has been a core component of the Nix package manager since its early days, embodying the fundamental principle of Nix: reproducible, atomic builds by defining software as derivations. While the newer, unified nix command now offers `nix build` as a more modern interface that consolidates many operations, nix-build remains widely used and understood as the classic way to initiate a build within the Nix ecosystem. Its stable and foundational role reflects its importance in the project's evolution and its continued relevance.

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