# Name

`nix-shell` - start an interactive shell based on a Nix expression

# Synopsis

`nix-shell`
  [`--arg` *name* *value*]
  [`--argstr` *name* *value*]
  [{`--attr` | `-A`} *attrPath*]
  [`--command` *cmd*]
  [`--run` *cmd*]
  [`--exclude` *regexp*]
  [`--pure`]
  [`--keep` *name*]
  {{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]}

# Disambiguation

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

# Description

The command `nix-shell` will build the dependencies of the specified
derivation, but not the derivation itself. It will then start an
interactive shell in which all environment variables defined by the
derivation *path* have been set to their corresponding values, and the
script `$stdenv/setup` has been sourced. This is useful for reproducing
the environment of a derivation for development.

If *path* is not given, `nix-shell` defaults to `shell.nix` if it
exists, and `default.nix` otherwise.

If *path* 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`.

If the derivation defines the variable `shellHook`, it will be run
after `$stdenv/setup` has been sourced. Since this hook is not executed
by regular Nix builds, it allows you to perform initialisation specific
to `nix-shell`. For example, the derivation attribute

```nix
shellHook =
  ''
    echo "Hello shell"
    export SOME_API_TOKEN="$(cat ~/.config/some-app/api-token)"
  '';
```

will cause `nix-shell` to print `Hello shell` and set the `SOME_API_TOKEN`
environment variable to a user-configured value.

# Options

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

- `--command` *cmd*

  In the environment of the derivation, run the shell command *cmd*.
  This command is executed in an interactive shell. (Use `--run` to
  use a non-interactive shell instead.) However, a call to `exit` is
  implicitly added to the command, so the shell will exit after
  running the command. To prevent this, add `return` at the end;
  e.g.  `--command "echo Hello; return"` will print `Hello` and then
  drop you into the interactive shell. This can be useful for doing
  any additional initialisation.

- `--run` *cmd*

  Like `--command`, but executes the command in a non-interactive
  shell. This means (among other things) that if you hit Ctrl-C while
  the command is running, the shell exits.

- `--exclude` *regexp*

  Do not build any dependencies whose store path matches the regular
  expression *regexp*. This option may be specified multiple times.

- `--pure`

  If this flag is specified, the environment is almost entirely
  cleared before the interactive shell is started, so you get an
  environment that more closely corresponds to the “real” Nix build. A
  few variables, in particular `HOME`, `USER` and `DISPLAY`, are
  retained.  Note that the shell used to run commands is obtained from
  [`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL) / `<nixpkgs>` from
  `NIX_PATH`, and therefore not affected by `--pure`.

- `--packages` / `-p` *packages*…

  Set up an environment in which the specified packages are present.
  The command line arguments are interpreted as attribute names inside
  the Nix Packages collection. Thus, `nix-shell --packages libjpeg openjdk`
  will start a shell in which the packages denoted by the attribute
  names `libjpeg` and `openjdk` are present.

- `-i` *interpreter*

  The chained script interpreter to be invoked by `nix-shell`. Only
  applicable in `#!`-scripts (described below).

- `--keep` *name*

  When a `--pure` shell is started, keep the listed environment
  variables.

{{#include ./opt-common.md}}

# Environment variables

- <span id="env-NIX_BUILD_SHELL">[`NIX_BUILD_SHELL`](#env-NIX_BUILD_SHELL)</span>