Name

nix-build - build a Nix expression

Synopsis

nix-build [paths…] [--arg name value] [--argstr name value] [{--attr | -A} attrPath] [--no-out-link] [--dry-run] [{--out-link | -o} outlink]

Disambiguation

This man page describes the command nix-build, which is distinct from nix build. For documentation on the latter, run nix build --help or see man nix3-build.

Description

The nix-build command builds the derivations described by the Nix expressions in paths. If the build succeeds, it places a symlink to the result in the current directory. The symlink is called result. If there are multiple Nix expressions, or the Nix expressions evaluate to multiple derivations, multiple sequentially numbered symlinks are created (result, result-2, and so on).

If no paths are specified, then nix-build will use default.nix in the current directory, if it exists.

If an element of paths starts with http:// or https://, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. The tarball must include a single top-level directory containing at least a file named default.nix.

nix-build is essentially a wrapper around nix-instantiate (to translate a high-level Nix expression to a low-level store derivation) and nix-store --realise (to build the store derivation).

Warning

The result of the build is automatically registered as a root of the Nix garbage collector. This root disappears automatically when the result symlink is deleted or renamed. So don’t rename the symlink.

Options

All options not listed here are passed to nix-store --realise, except for --arg and --attr / -A which are passed to nix-instantiate.

--no-out-link

Do not create a symlink to the output path. Note that as a result the output does not become a root of the garbage collector, and so might be deleted by nix-store --gc.

  • --dry-run

    Show what store paths would be built or downloaded.

  • --out-link / -o outlink

    Change the name of the symlink to the output path created from result to outlink.

    • Special exit codes for build failure

    1xx status codes are used when requested builds failed. The following codes are in use:

    With the --keep-going flag it's possible for multiple failures to occur. In this case the 1xx status codes are or combined using bitwise OR.

    0b1100100
     ^^^^
     |||`- timeout
     ||`-- output hash mismatch
     |`--- build failure
     `---- not deterministic

    Common Options

    Most Nix commands accept the following command-line options:

    Note

    See man nix.conf for overriding configuration settings with command line flags.

    Common Environment Variables

    Most Nix commands interpret the following environment variables:

    XDG Base Directories

    Nix follows the XDG Base Directory Specification.

    For backwards compatibility, Nix commands will follow the standard only when use-xdg-base-directories is enabled. New Nix commands (experimental) conform to the standard by default.

    The following environment variables are used to determine locations of various state and configuration files:

    In addition, setting the following environment variables overrides the XDG base directories:

    When use-xdg-base-directories is enabled, the configuration directory is:

    1. $NIX_CONFIG_HOME, if it is defined
    2. Otherwise, $XDG_CONFIG_HOME/nix, if XDG_CONFIG_HOME is defined
    3. Otherwise, ~/.config/nix.

    Likewise for the state and cache directories.

    Examples

    $ nix-build '<nixpkgs>' --attr firefox
store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
/nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls -l result
lrwxrwxrwx  ...  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls ./result/bin/
firefox  firefox-config

    If a derivation has multiple outputs, nix-build will build the default (first) output. You can also build all outputs:

    $ nix-build '<nixpkgs>' --attr openssl.all

    This will create a symlink for each output named result-outputname. The suffix is omitted if the output name is out. So if openssl has outputs out, bin and man, nix-build will create symlinks result, result-bin and result-man. It’s also possible to build a specific output:

    $ nix-build '<nixpkgs>' --attr openssl.man

    This will create a symlink result-man.

    Build a Nix expression given on the command line:

    $ nix-build --expr 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
$ cat ./result
bar

    Build the GNU Hello package from the latest revision of the master branch of Nixpkgs:

    $ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz --attr hello