.\" -*- mode: troff; coding: utf-8 -*-
.TH "nix3-shell" "1" ""
.PP
\fBWarning\fR: This program is \fBexperimental\fR and its interface is subject to change.
.SH Name
\fCnix shell\fR - run a shell in which the specified packages are available
.SH Synopsis
\fCnix shell\fR [\fIoption\fR\[u2026]] \fIinstallables\fR\[u2026]
.SH Examples
.IP "\(bu" 2
Start a shell providing \fCyoutube-dl\fR from the \fCnixpkgs\fR flake:
.LP
.EX
# nix shell nixpkgs#youtube-dl
# youtube-dl --version
2020.11.01.1
.EE
.IP "\(bu" 2
Start a shell providing GNU Hello from NixOS 20.03:
.LP
.EX
# nix shell nixpkgs/nixos-20.03#hello
.EE
.IP "\(bu" 2
Run GNU Hello:
.LP
.EX
# nix shell nixpkgs#hello -c hello --greeting 'Hi everybody!'
Hi everybody!
.EE
.IP "\(bu" 2
Run GNU Hello in a chroot store:
.LP
.EX
# nix shell --store \(ti/my-nix nixpkgs#hello -c hello
.EE
.IP "\(bu" 2
Start a shell providing GNU Hello in a chroot store:
.LP
.EX
# nix shell --store \(ti/my-nix nixpkgs#hello nixpkgs#bashInteractive -c bash
.EE
.IP
Note that it\[u2019]s necessary to specify \fCbash\fR explicitly because your
default shell (e.g. \fC/bin/bash\fR) generally will not exist in the
chroot.
.SH Description
\fCnix shell\fR runs a command in an environment in which the \fC$PATH\fR variable
provides the specified \fIinstallables\fR. If no command is specified, it starts the
default shell of your user account specified by \fC$SHELL\fR.
.SH Options
.IP "\(bu" 2
\fC--command\fR / \fC-c\fR \fIcommand\fR \fIargs\fR
.br
Command and arguments to be executed, defaulting to \fC$SHELL\fR
.IP "\(bu" 2
\fC--ignore-environment\fR / \fC-i\fR
.br
Clear the entire environment (except those specified with \fC--keep\fR).
.IP "\(bu" 2
\fC--keep\fR / \fC-k\fR \fIname\fR
.br
Keep the environment variable \fIname\fR.
.IP "\(bu" 2
\fC--unset\fR / \fC-u\fR \fIname\fR
.br
Unset the environment variable \fIname\fR.
.LP
\fBCommon evaluation options:\fR
.IP "\(bu" 2
\fC--arg\fR \fIname\fR \fIexpr\fR
.br
Pass the value \fIexpr\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 2
\fC--argstr\fR \fIname\fR \fIstring\fR
.br
Pass the string \fIstring\fR as the argument \fIname\fR to Nix functions.
.IP "\(bu" 2
\fC--eval-store\fR \fIstore-url\fR
.br
The Nix store to use for evaluations.
.IP "\(bu" 2
\fC--impure\fR
.br
Allow access to mutable paths and repositories.
.IP "\(bu" 2
\fC--include\fR / \fC-I\fR \fIpath\fR
.br
Add \fIpath\fR to the list of locations used to look up \fC<...>\fR file names.
.IP "\(bu" 2
\fC--override-flake\fR \fIoriginal-ref\fR \fIresolved-ref\fR
.br
Override the flake registries, redirecting \fIoriginal-ref\fR to \fIresolved-ref\fR.
.LP
\fBCommon flake-related options:\fR
.IP "\(bu" 2
\fC--commit-lock-file\fR
.br
Commit changes to the flake\[u2019]s lock file.
.IP "\(bu" 2
\fC--inputs-from\fR \fIflake-url\fR
.br
Use the inputs of the specified flake as registry entries.
.IP "\(bu" 2
\fC--no-registries\fR
.br
Don\[u2019]t allow lookups in the flake registries. This option is deprecated; use \fC--no-use-registries\fR.
.IP "\(bu" 2
\fC--no-update-lock-file\fR
.br
Do not allow any updates to the flake\[u2019]s lock file.
.IP "\(bu" 2
\fC--no-write-lock-file\fR
.br
Do not write the flake\[u2019]s newly generated lock file.
.IP "\(bu" 2
\fC--override-input\fR \fIinput-path\fR \fIflake-url\fR
.br
Override a specific flake input (e.g. \fCdwarffs/nixpkgs\fR). This implies \fC--no-write-lock-file\fR.
.IP "\(bu" 2
\fC--recreate-lock-file\fR
.br
Recreate the flake\[u2019]s lock file from scratch.
.IP "\(bu" 2
\fC--update-input\fR \fIinput-path\fR
.br
Update a specific flake input (ignoring its previous entry in the lock file).
.LP
\fBOptions that change the interpretation of installables:\fR
.IP "\(bu" 2
\fC--derivation\fR
.br
Operate on the store derivation rather than its outputs.
.IP "\(bu" 2
\fC--expr\fR \fIexpr\fR
.br
Interpret installables as attribute paths relative to the Nix expression \fIexpr\fR.
.IP "\(bu" 2
\fC--file\fR / \fC-f\fR \fIfile\fR
.br
Interpret installables as attribute paths relative to the Nix expression stored in \fIfile\fR. If \fIfile\fR is the character -, then a Nix expression will be read from standard input.