path: root/doc/manual/nix-shell.xml

<refentry xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xml:id="sec-nix-shell">

<refmeta>
  <refentrytitle>nix-shell</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
</refmeta>

<refnamediv>
  <refname>nix-shell</refname>
  <refpurpose>start an interactive shell based on a Nix expression</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-shell</command>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--attr</option></arg>
        <arg choice='plain'><option>-A</option></arg>
      </group>
      <replaceable>attrPath</replaceable>
    </arg>
    <arg><option>--command</option> <replaceable>cmd</replaceable></arg>
    <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
    <arg><option>--pure</option></arg>
    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>The command <command>nix-shell --run-env</command> 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 have been set to their
corresponding values, and the script <literal>$stdenv/setup</literal>
has been sourced.  This is useful for reproducing the environment of a
derivation for development.</para>

</refsection>


<refsection><title>Options</title>

<para>All options not listed here are passed to <command>nix-store
--realise</command>, except for <option>--arg</option> and
<option>--attr</option> / <option>-A</option> which are passed to
<command>nix-instantiate</command>.  <phrase condition="manual">See
also <xref linkend="sec-common-options" />.</phrase></para>

<variablelist>

  <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>

    <listitem><para>In the environment of the derivation, run the
    shell command <replaceable>cmd</replaceable> instead of starting
    an interactive shell.  However, if you end the shell command with
    <literal>return</literal>, you still get an interactive shell.
    This can be useful for doing any additional
    initialisation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>

    <listitem><para>Do not build any dependencies whose store path
    matches the regular expression <replaceable>regexp</replaceable>.
    This option may be specified multiple times.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--pure</option></term>

    <listitem><para>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
    <envar>HOME</envar>, <envar>USER</envar> and
    <envar>DISPLAY</envar>, are retained.  Note that
    <filename>~/.bashrc</filename> and (depending on your Bash
    installation) <filename>/etc/bashrc</filename> are still sourced,
    so any variables set there will affect the interactive
    shell.</para></listitem>

  </varlistentry>

</variablelist>

<para>The following common options are supported:</para>

<variablelist condition="manpage">
  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
</variablelist>

</refsection>


<refsection><title>Examples</title>

<para>To build the dependencies of the package Pan, and start an
interactive shell in which to build it:

<screen>
$ nix-shell '&lt;nixpkgs>' -A pan
$ unpackPhase
$ cd pan-*
$ configurePhase
$ buildPhase
$ ./pan/gui/pan
</screen>

To clear the environment first, and do some additional automatic
initialisation of the interactive shell:

<screen>
$ nix-shell '&lt;nixpkgs>' -A pan --pure \
    --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
</screen>

</para>

</refsection>


<refsection condition="manpage"><title>Environment variables</title>

<variablelist>
  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
</variablelist>

</refsection>


</refentry>