Warning: This program is experimental and its interface is subject to change.
Name
nix
- a tool for reproducible and declarative configuration management
Synopsis
nix
[option...] subcommand
where subcommand is one of the following:
Main commands:
nix build
- build a derivation or fetch a store pathnix develop
- run a bash shell that provides the build environment of a derivationnix flake
- manage Nix flakesnix help
- show help aboutnix
or a particular subcommandnix profile
- manage Nix profilesnix repl
- start an interactive environment for evaluating Nix expressionsnix run
- run a Nix applicationnix search
- search for packagesnix shell
- run a shell in which the specified packages are available
Infrequently used commands:
nix bundle
- bundle an application so that it works outside of the Nix storenix copy
- copy paths between Nix storesnix edit
- open the Nix expression of a Nix package in $EDITORnix eval
- evaluate a Nix expressionnix fmt
- reformat your code in the standard stylenix log
- show the build log of the specified packages or paths, if availablenix path-info
- query information about store pathsnix registry
- manage the flake registrynix why-depends
- show why a package has another package in its closure
Utility/scripting commands:
nix daemon
- daemon to perform store operations on behalf of non-root clientsnix describe-stores
- show registered store types and their available optionsnix hash
- compute and convert cryptographic hashesnix key
- generate and convert Nix signing keysnix nar
- create or inspect NAR filesnix print-dev-env
- print shell code that can be sourced by bash to reproduce the build environment of a derivationnix realisation
- manipulate a Nix realisationnix show-config
- show the Nix configurationnix show-derivation
- show the contents of a store derivationnix store
- manipulate a Nix store
Commands for upgrading or troubleshooting your Nix installation:
nix doctor
- check your system for potential problems and print a PASS or FAIL for each checknix upgrade-nix
- upgrade Nix to the latest stable version
Examples
-
Create a new flake:
# nix flake new hello # cd hello
-
Build the flake in the current directory:
# nix build # ./result/bin/hello Hello, world!
-
Run the flake in the current directory:
# nix run Hello, world!
-
Start a development shell for hacking on this flake:
# nix develop # unpackPhase # cd hello-* # configurePhase # buildPhase # ./hello Hello, world! # installPhase # ../outputs/out/bin/hello Hello, world!
Description
Nix is a tool for building software, configurations and other artifacts in a reproducible and declarative way. For more information, see the Nix homepage or the Nix manual.
Installables
Many nix
subcommands operate on one or more installables. These are
command line arguments that represent something that can be built in
the Nix store. Here are the recognised types of installables:
-
Flake output attributes:
nixpkgs#hello
These have the form flakeref[
#
attrpath], where flakeref is a flake reference and attrpath is an optional attribute path. For more information on flakes, see thenix flake
manual page. Flake references are most commonly a flake identifier in the flake registry (e.g.nixpkgs
), or a raw path (e.g./path/to/my-flake
or.
or../foo
), or a full URL (e.g.github:nixos/nixpkgs
orpath:.
)When the flake reference is a raw path (a path without any URL scheme), it is interpreted as a
path:
orgit+file:
url in the following way:-
If the path is within a Git repository, then the url will be of the form
git+file://[GIT_REPO_ROOT]?dir=[RELATIVE_FLAKE_DIR_PATH]
whereGIT_REPO_ROOT
is the path to the root of the git repository, andRELATIVE_FLAKE_DIR_PATH
is the path (relative to the directory root) of the closest parent of the given path that contains aflake.nix
within the git repository. If no such directory exists, then Nix will error-out.Note that the search will only include files indexed by git. In particular, files which are matched by
.gitignore
or have never beengit add
-ed will not be available in the flake. If this is undesirable, specifypath:<directory>
explicitly;For example, if
/foo/bar
is a git repository with the following structure:. └── baz ├── blah │ └── file.txt └── flake.nix
Then
/foo/bar/baz/blah
will resolve togit+file:///foo/bar?dir=baz
-
If the supplied path is not a git repository, then the url will have the form
path:FLAKE_DIR_PATH
whereFLAKE_DIR_PATH
is the closest parent of the supplied path that contains aflake.nix
file (within the same file-system). If no such directory exists, then Nix will error-out.For example, if
/foo/bar/flake.nix
exists, then/foo/bar/baz/
will resolve topath:/foo/bar
If attrpath is omitted, Nix tries some default values; for most subcommands, the default is
packages.
system.default
(e.g.packages.x86_64-linux.default
), but some subcommands have other defaults. If attrpath is specified, attrpath is interpreted as relative to one or more prefixes; for most subcommands, these arepackages.
system,legacyPackages.*system*
and the empty prefix. Thus, onx86_64-linux
nix build nixpkgs#hello
will try to build the attributespackages.x86_64-linux.hello
,legacyPackages.x86_64-linux.hello
andhello
. -
-
Store paths:
/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
These are paths inside the Nix store, or symlinks that resolve to a path in the Nix store.
-
Store derivations:
/nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv
Store derivations are store paths with extension
.drv
and are a low-level representation of a build-time dependency graph used internally by Nix. By default, if you pass a store derivation to anix
subcommand, it will operate on the output paths of the derivation. For example,nix path-info
prints information about the output paths:# nix path-info --json /nix/store/p7gp6lxdg32h4ka1q398wd9r2zkbbz2v-hello-2.10.drv [{"path":"/nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10",…}]
If you want to operate on the store derivation itself, pass the
--derivation
flag. -
Nix attributes:
--file /path/to/nixpkgs hello
When the
-f
/--file
path option is given, installables are interpreted as attribute paths referencing a value returned by evaluating the Nix file path. -
Nix expressions:
--expr '(import <nixpkgs> {}).hello.overrideDerivation (prev: { name = "my-hello"; })'
.When the
--expr
option is given, all installables are interpreted as Nix expressions. You may need to specify--impure
if the expression references impure inputs (such as<nixpkgs>
).
For most commands, if no installable is specified, the default is .
,
i.e. Nix will operate on the default flake output attribute of the
flake in the current directory.
Nix stores
Most nix
subcommands operate on a Nix store.
TODO: list store types, options
Options
-
--help
Show usage information. -
--offline
Disable substituters and consider all previously downloaded files up-to-date. -
--option
name value
Set the Nix configuration setting name to value (overridingnix.conf
). -
--refresh
Consider all previously downloaded files out-of-date. -
--version
Show version information.
Logging-related options:
-
--debug
Set the logging verbosity level to 'debug'. -
--log-format
format
Set the format of log output; one ofraw
,internal-json
,bar
orbar-with-logs
. -
--print-build-logs
/-L
Print full build logs on standard error. -
--quiet
Decrease the logging verbosity level. -
--verbose
/-v
Increase the logging verbosity level.
Options to override configuration settings:
-
--accept-flake-config
Enable theaccept-flake-config
setting. -
--access-tokens
value
Set theaccess-tokens
setting. -
--allow-dirty
Enable theallow-dirty
setting. -
--allow-import-from-derivation
Enable theallow-import-from-derivation
setting. -
--allow-new-privileges
Enable theallow-new-privileges
setting. -
--allow-symlinked-store
Enable theallow-symlinked-store
setting. -
--allow-unsafe-native-code-during-evaluation
Enable theallow-unsafe-native-code-during-evaluation
setting. -
--allowed-impure-host-deps
value
Set theallowed-impure-host-deps
setting. -
--allowed-uris
value
Set theallowed-uris
setting. -
--allowed-users
value
Set theallowed-users
setting. -
--auto-optimise-store
Enable theauto-optimise-store
setting. -
--bash-prompt
value
Set thebash-prompt
setting. -
--bash-prompt-suffix
value
Set thebash-prompt-suffix
setting. -
--build-hook
value
Set thebuild-hook
setting. -
--build-poll-interval
value
Set thebuild-poll-interval
setting. -
--build-users-group
value
Set thebuild-users-group
setting. -
--builders
value
Set thebuilders
setting. -
--builders-use-substitutes
Enable thebuilders-use-substitutes
setting. -
--commit-lockfile-summary
value
Set thecommit-lockfile-summary
setting. -
--compress-build-log
Enable thecompress-build-log
setting. -
--connect-timeout
value
Set theconnect-timeout
setting. -
--cores
value
Set thecores
setting. -
--diff-hook
value
Set thediff-hook
setting. -
--download-attempts
value
Set thedownload-attempts
setting. -
--enforce-determinism
Enable theenforce-determinism
setting. -
--eval-cache
Enable theeval-cache
setting. -
--experimental-features
value
Set theexperimental-features
setting. -
--extra-access-tokens
value
Append to theaccess-tokens
setting. -
--extra-allowed-impure-host-deps
value
Append to theallowed-impure-host-deps
setting. -
--extra-allowed-uris
value
Append to theallowed-uris
setting. -
--extra-allowed-users
value
Append to theallowed-users
setting. -
--extra-experimental-features
value
Append to theexperimental-features
setting. -
--extra-extra-platforms
value
Append to theextra-platforms
setting. -
--extra-hashed-mirrors
value
Append to thehashed-mirrors
setting. -
--extra-ignored-acls
value
Append to theignored-acls
setting. -
--extra-nix-path
value
Append to thenix-path
setting. -
--extra-platforms
value
Set theextra-platforms
setting. -
--extra-plugin-files
value
Append to theplugin-files
setting. -
--extra-sandbox-paths
value
Append to thesandbox-paths
setting. -
--extra-secret-key-files
value
Append to thesecret-key-files
setting. -
--extra-substituters
value
Append to thesubstituters
setting. -
--extra-system-features
value
Append to thesystem-features
setting. -
--extra-trusted-public-keys
value
Append to thetrusted-public-keys
setting. -
--extra-trusted-substituters
value
Append to thetrusted-substituters
setting. -
--extra-trusted-users
value
Append to thetrusted-users
setting. -
--fallback
Enable thefallback
setting. -
--filter-syscalls
Enable thefilter-syscalls
setting. -
--flake-registry
value
Set theflake-registry
setting. -
--fsync-metadata
Enable thefsync-metadata
setting. -
--gc-reserved-space
value
Set thegc-reserved-space
setting. -
--hashed-mirrors
value
Set thehashed-mirrors
setting. -
--http-connections
value
Set thehttp-connections
setting. -
--http2
Enable thehttp2
setting. -
--ignored-acls
value
Set theignored-acls
setting. -
--impersonate-linux-26
Enable theimpersonate-linux-26
setting. -
--keep-build-log
Enable thekeep-build-log
setting. -
--keep-derivations
Enable thekeep-derivations
setting. -
--keep-env-derivations
Enable thekeep-env-derivations
setting. -
--keep-failed
Enable thekeep-failed
setting. -
--keep-going
Enable thekeep-going
setting. -
--keep-outputs
Enable thekeep-outputs
setting. -
--log-lines
value
Set thelog-lines
setting. -
--max-build-log-size
value
Set themax-build-log-size
setting. -
--max-free
value
Set themax-free
setting. -
--max-jobs
value
Set themax-jobs
setting. -
--max-silent-time
value
Set themax-silent-time
setting. -
--min-free
value
Set themin-free
setting. -
--min-free-check-interval
value
Set themin-free-check-interval
setting. -
--nar-buffer-size
value
Set thenar-buffer-size
setting. -
--narinfo-cache-negative-ttl
value
Set thenarinfo-cache-negative-ttl
setting. -
--narinfo-cache-positive-ttl
value
Set thenarinfo-cache-positive-ttl
setting. -
--netrc-file
value
Set thenetrc-file
setting. -
--nix-path
value
Set thenix-path
setting. -
--no-accept-flake-config
Disable theaccept-flake-config
setting. -
--no-allow-dirty
Disable theallow-dirty
setting. -
--no-allow-import-from-derivation
Disable theallow-import-from-derivation
setting. -
--no-allow-new-privileges
Disable theallow-new-privileges
setting. -
--no-allow-symlinked-store
Disable theallow-symlinked-store
setting. -
--no-allow-unsafe-native-code-during-evaluation
Disable theallow-unsafe-native-code-during-evaluation
setting. -
--no-auto-optimise-store
Disable theauto-optimise-store
setting. -
--no-builders-use-substitutes
Disable thebuilders-use-substitutes
setting. -
--no-compress-build-log
Disable thecompress-build-log
setting. -
--no-enforce-determinism
Disable theenforce-determinism
setting. -
--no-eval-cache
Disable theeval-cache
setting. -
--no-fallback
Disable thefallback
setting. -
--no-filter-syscalls
Disable thefilter-syscalls
setting. -
--no-fsync-metadata
Disable thefsync-metadata
setting. -
--no-http2
Disable thehttp2
setting. -
--no-impersonate-linux-26
Disable theimpersonate-linux-26
setting. -
--no-keep-build-log
Disable thekeep-build-log
setting. -
--no-keep-derivations
Disable thekeep-derivations
setting. -
--no-keep-env-derivations
Disable thekeep-env-derivations
setting. -
--no-keep-failed
Disable thekeep-failed
setting. -
--no-keep-going
Disable thekeep-going
setting. -
--no-keep-outputs
Disable thekeep-outputs
setting. -
--no-preallocate-contents
Disable thepreallocate-contents
setting. -
--no-print-missing
Disable theprint-missing
setting. -
--no-pure-eval
Disable thepure-eval
setting. -
--no-require-sigs
Disable therequire-sigs
setting. -
--no-restrict-eval
Disable therestrict-eval
setting. -
--no-run-diff-hook
Disable therun-diff-hook
setting. -
--no-sandbox
Disable sandboxing. -
--no-sandbox-fallback
Disable thesandbox-fallback
setting. -
--no-show-trace
Disable theshow-trace
setting. -
--no-substitute
Disable thesubstitute
setting. -
--no-sync-before-registering
Disable thesync-before-registering
setting. -
--no-trace-function-calls
Disable thetrace-function-calls
setting. -
--no-use-case-hack
Disable theuse-case-hack
setting. -
--no-use-registries
Disable theuse-registries
setting. -
--no-use-sqlite-wal
Disable theuse-sqlite-wal
setting. -
--no-warn-dirty
Disable thewarn-dirty
setting. -
--plugin-files
value
Set theplugin-files
setting. -
--post-build-hook
value
Set thepost-build-hook
setting. -
--pre-build-hook
value
Set thepre-build-hook
setting. -
--preallocate-contents
Enable thepreallocate-contents
setting. -
--print-missing
Enable theprint-missing
setting. -
--pure-eval
Enable thepure-eval
setting. -
--relaxed-sandbox
Enable sandboxing, but allow builds to disable it. -
--repeat
value
Set therepeat
setting. -
--require-sigs
Enable therequire-sigs
setting. -
--restrict-eval
Enable therestrict-eval
setting. -
--run-diff-hook
Enable therun-diff-hook
setting. -
--sandbox
Enable sandboxing. -
--sandbox-build-dir
value
Set thesandbox-build-dir
setting. -
--sandbox-dev-shm-size
value
Set thesandbox-dev-shm-size
setting. -
--sandbox-fallback
Enable thesandbox-fallback
setting. -
--sandbox-paths
value
Set thesandbox-paths
setting. -
--secret-key-files
value
Set thesecret-key-files
setting. -
--show-trace
Enable theshow-trace
setting. -
--stalled-download-timeout
value
Set thestalled-download-timeout
setting. -
--store
value
Set thestore
setting. -
--substitute
Enable thesubstitute
setting. -
--substituters
value
Set thesubstituters
setting. -
--sync-before-registering
Enable thesync-before-registering
setting. -
--system
value
Set thesystem
setting. -
--system-features
value
Set thesystem-features
setting. -
--tarball-ttl
value
Set thetarball-ttl
setting. -
--timeout
value
Set thetimeout
setting. -
--trace-function-calls
Enable thetrace-function-calls
setting. -
--trusted-public-keys
value
Set thetrusted-public-keys
setting. -
--trusted-substituters
value
Set thetrusted-substituters
setting. -
--trusted-users
value
Set thetrusted-users
setting. -
--use-case-hack
Enable theuse-case-hack
setting. -
--use-registries
Enable theuse-registries
setting. -
--use-sqlite-wal
Enable theuse-sqlite-wal
setting. -
--user-agent-suffix
value
Set theuser-agent-suffix
setting. -
--warn-dirty
Enable thewarn-dirty
setting.