about summary refs log tree commit diff
path: root/doc/manual/command-ref/nix-shell.xml
blob: bb4a4e4201227a70929f866bd9b199fd0818f881 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
<refentry xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      version="5.0"
      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>
    <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>--run</option> <replaceable>cmd</replaceable></arg>
    <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
    <arg><option>--pure</option></arg>
    <arg><option>--keep</option> <replaceable>name</replaceable></arg>
    <group choice='req'>
      <arg choice='plain'>
        <group choice='req'>
          <arg choice='plain'><option>--packages</option></arg>
          <arg choice='plain'><option>-p</option></arg>
        </group>
        <arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
      </arg>
      <arg><replaceable>path</replaceable></arg>
    </group>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>The command <command>nix-shell</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
<replaceable>path</replaceable> 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>

<para>If <replaceable>path</replaceable> is not given,
<command>nix-shell</command> defaults to
<filename>shell.nix</filename> if it exists, and
<filename>default.nix</filename> otherwise.</para>

<para>If <replaceable>path</replaceable> starts with
<literal>http://</literal> or <literal>https://</literal>, 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
<filename>default.nix</filename>.</para>

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

<programlisting>
shellHook =
  ''
    echo "Hello shell"
  '';
</programlisting>

will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</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>. This command is
    executed in an interactive shell. (Use <option>--run</option> to
    use a non-interactive shell instead.) However, a call to
    <literal>exit</literal> is implicitly added to the command, so the
    shell will exit after running the command. To prevent this, add
    <literal>return</literal> at the end; e.g. <literal>--command
    "echo Hello; return"</literal> will print <literal>Hello</literal>
    and then drop you into the interactive shell. This can be useful
    for doing any additional initialisation.</para></listitem>

  </varlistentry>

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

    <listitem><para>Like <option>--command</option>, 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.</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>

  <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term>

    <listitem><para>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,
    <literal>nix-shell -p libjpeg openjdk</literal> will start a shell
    in which the packages denoted by the attribute names
    <varname>libjpeg</varname> and <varname>openjdk</varname> are
    present.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term>

    <listitem><para>The chained script interpreter to be invoked by
    <command>nix-shell</command>. Only applicable in
    <literal>#!</literal>-scripts (described <link
    linkend="ssec-nix-shell-shebang">below</link>).</para>

    </listitem></varlistentry>

  <varlistentry><term><option>--keep</option> <replaceable>name</replaceable></term>

    <listitem><para>When a <option>--pure</option> shell is started,
    keep the listed environment variables.</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>Environment variables</title>

<variablelist>

  <varlistentry><term><envar>NIX_BUILD_SHELL</envar></term>
    
    <listitem><para>Shell used to start the interactive environment. 
    Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem>

  </varlistentry>

</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
[nix-shell]$ unpackPhase
[nix-shell]$ cd pan-*
[nix-shell]$ configurePhase
[nix-shell]$ buildPhase
[nix-shell]$ ./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>

Nix expressions can also be given on the command line.  For instance,
the following starts a shell containing the packages
<literal>sqlite</literal> and <literal>libX11</literal>:

<screen>
$ nix-shell -E 'with import &lt;nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
</screen>

A shorter way to do the same is:

<screen>
$ nix-shell -p sqlite xorg.libX11
[nix-shell]$ echo $NIX_LDFLAGS
… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
</screen>

The <command>-p</command> flag looks up Nixpkgs in the Nix search
path. You can override it by passing <option>-I</option> or setting
<envar>NIX_PATH</envar>. For example, the following gives you a shell
containing the Pan package from a specific revision of Nixpkgs:

<screen>
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz

[nix-shell:~]$ pan --version
Pan 0.139
</screen>

</para>

</refsection>


<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title>

<para>You can use <command>nix-shell</command> as a script interpreter
to allow scripts written in arbitrary languages to obtain their own
dependencies via Nix. This is done by starting the script with the
following lines:

<programlisting>
#! /usr/bin/env nix-shell
#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable>
</programlisting>

where <replaceable>real-interpreter</replaceable> is the “real” script
interpreter that will be invoked by <command>nix-shell</command> after
it has obtained the dependencies and initialised the environment, and
<replaceable>packages</replaceable> are the attribute names of the
dependencies in Nixpkgs.</para>

<para>The lines starting with <literal>#! nix-shell</literal> specify
<command>nix-shell</command> options (see above). Note that you cannot
write <literal>#! /usr/bin/env nix-shell -i ...</literal> because
many operating systems only allow one argument in
<literal>#!</literal> lines.</para>

<para>For example, here is a Python script that depends on Python and
the <literal>prettytable</literal> package:

<programlisting>
#! /usr/bin/env nix-shell
#! nix-shell -i python -p python pythonPackages.prettytable

import prettytable

# Print a simple table.
t = prettytable.PrettyTable(["N", "N^2"])
for n in range(1, 10): t.add_row([n, n * n])
print t
</programlisting>

</para>

<para>Similarly, the following is a Perl script that specifies that it
requires Perl and the <literal>HTML::TokeParser::Simple</literal> and
<literal>LWP</literal> packages:

<programlisting>
#! /usr/bin/env nix-shell
#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP

use HTML::TokeParser::Simple;

# Fetch nixos.org and print all hrefs.
my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');

while (my $token = $p->get_tag("a")) {
    my $href = $token->get_attr("href");
    print "$href\n" if $href;
}
</programlisting>

</para>

<para>Sometimes you need to pass a simple Nix expression to customize
a package like Terraform:

<programlisting><![CDATA[
#! /usr/bin/env nix-shell
#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"

terraform apply
]]></programlisting>

<note><para>You must use double quotes (<literal>"</literal>) when
passing a simple Nix expression in a nix-shell shebang.</para></note>
</para>

<para>Finally, using the merging of multiple nix-shell shebangs the
following Haskell script uses a specific branch of Nixpkgs/NixOS (the
18.03 stable branch):

<programlisting><![CDATA[
#! /usr/bin/env nix-shell
#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-18.03.tar.gz

import Network.HTTP
import Text.HTML.TagSoup

-- Fetch nixos.org and print all hrefs.
main = do
  resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
  body <- getResponseBody resp
  let tags = filter (isTagOpenName "a") $ parseTags body
  let tags' = map (fromAttrib "href") tags
  mapM_ putStrLn $ filter (/= "") tags'
]]></programlisting>

If you want to be even more precise, you can specify a specific
revision of Nixpkgs:

<programlisting>
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
</programlisting>

</para>

<para>The examples above all used <option>-p</option> to get
dependencies from Nixpkgs. You can also use a Nix expression to build
your own dependencies. For example, the Python example could have been
written as:

<programlisting>
#! /usr/bin/env nix-shell
#! nix-shell deps.nix -i python
</programlisting>

where the file <filename>deps.nix</filename> in the same directory
as the <literal>#!</literal>-script contains:

<programlisting>
with import &lt;nixpkgs> {};

runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
</programlisting>

</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>