pyrox.dev
1# Python
2
3## User Guide
4
5### Using Python
6
7#### Overview
8
9Several versions of the Python interpreter are available on Nix, as well as a
10high amount of packages. The attribute `python` refers to the default
11interpreter, which is currently CPython 2.7. It is also possible to refer to
12specific versions, e.g. `python35` refers to CPython 3.5, and `pypy` refers to
13the default PyPy interpreter.
14
15Python is used a lot, and in different ways. This affects also how it is
16packaged. In the case of Python on Nix, an important distinction is made between
17whether the package is considered primarily an application, or whether it should
18be used as a library, i.e., of primary interest are the modules in
19`site-packages` that should be importable.
20
21In the Nixpkgs tree Python applications can be found throughout, depending on
22what they do, and are called from the main package set. Python libraries,
23however, are in separate sets, with one set per interpreter version.
24
25The interpreters have several common attributes. One of these attributes is
26`pkgs`, which is a package set of Python libraries for this specific
27interpreter. E.g., the `toolz` package corresponding to the default interpreter
28is `python.pkgs.toolz`, and the CPython 3.5 version is `python35.pkgs.toolz`.
29The main package set contains aliases to these package sets, e.g.
30`pythonPackages` refers to `python.pkgs` and `python35Packages` to
31`python35.pkgs`.
32
33#### Installing Python and packages
34
35The Nix and NixOS manuals explain how packages are generally installed. In the
36case of Python and Nix, it is important to make a distinction between whether the
37package is considered an application or a library.
38
39Applications on Nix are typically installed into your user
40profile imperatively using `nix-env -i`, and on NixOS declaratively by adding the
41package name to `environment.systemPackages` in `/etc/nixos/configuration.nix`.
42Dependencies such as libraries are automatically installed and should not be
43installed explicitly.
44
45The same goes for Python applications and libraries. Python applications can be
46installed in your profile. But Python libraries you would like to use for
47development cannot be installed, at least not individually, because they won't
48be able to find each other resulting in import errors. Instead, it is possible
49to create an environment with `python.buildEnv` or `python.withPackages` where
50the interpreter and other executables are able to find each other and all of the
51modules.
52
53In the following examples we create an environment with Python 3.5, `numpy` and
54`toolz`. As you may imagine, there is one limitation here, and that's that
55you can install only one environment at a time. You will notice the complaints
56about collisions when you try to install a second environment.
57
58##### Environment defined in separate `.nix` file
59
60Create a file, e.g. `build.nix`, with the following expression
61```nix
62with import <nixpkgs> {};
63
64python35.withPackages (ps: with ps; [ numpy toolz ])
65```
66and install it in your profile with
67```shell
68nix-env -if build.nix
69```
70Now you can use the Python interpreter, as well as the extra packages (`numpy`,
71`toolz`) that you added to the environment.
72
73##### Environment defined in `~/.config/nixpkgs/config.nix`
74
75If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
76using `config.nix`,
77```nix
78{ # ...
79
80 packageOverrides = pkgs: with pkgs; {
81 myEnv = python35.withPackages (ps: with ps; [ numpy toolz ]);
82 };
83}
84```
85and install it in your profile with
86```shell
87nix-env -iA nixpkgs.myEnv
88```
89The environment is is installed by referring to the attribute, and considering
90the `nixpkgs` channel was used.
91
92##### Environment defined in `/etc/nixos/configuration.nix`
93
94For the sake of completeness, here's another example how to install the environment system-wide.
95
96```nix
97{ # ...
98
99 environment.systemPackages = with pkgs; [
100 (python35.withPackages(ps: with ps; [ numpy toolz ]))
101 ];
102}
103```
104
105#### Temporary Python environment with `nix-shell`
106
107The examples in the previous section showed how to install a Python environment
108into a profile. For development you may need to use multiple environments.
109`nix-shell` gives the possibility to temporarily load another environment, akin
110to `virtualenv`.
111
112There are two methods for loading a shell with Python packages. The first and recommended method
113is to create an environment with `python.buildEnv` or `python.withPackages` and load that. E.g.
114```sh
115$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
116```
117opens a shell from which you can launch the interpreter
118```sh
119[nix-shell:~] python3
120```
121The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
122
123```sh
124$ nix-shell -p python35.pkgs.numpy python35.pkgs.toolz
125```
126Again, it is possible to launch the interpreter from the shell.
127The Python interpreter has the attribute `pkgs` which contains all Python libraries for that specific interpreter.
128
129##### Load environment from `.nix` expression
130As explained in the Nix manual, `nix-shell` can also load an
131expression from a `.nix` file. Say we want to have Python 3.5, `numpy`
132and `toolz`, like before, in an environment. Consider a `shell.nix` file
133with
134```nix
135with import <nixpkgs> {};
136
137python35.withPackages (ps: [ps.numpy ps.toolz])
138```
139Executing `nix-shell` gives you again a Nix shell from which you can run Python.
140
141What's happening here?
142
1431. We begin with importing the Nix Packages collections. `import <nixpkgs>` imports the `<nixpkgs>` function, `{}` calls it and the `with` statement brings all attributes of `nixpkgs` in the local scope. These attributes form the main package set.
1442. Then we create a Python 3.5 environment with the `withPackages` function.
1453. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set.
146
147##### Execute command with `--run`
148A convenient option with `nix-shell` is the `--run`
149option, with which you can execute a command in the `nix-shell`. We can
150e.g. directly open a Python shell
151```sh
152$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
153```
154or run a script
155```sh
156$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
157```
158
159##### `nix-shell` as shebang
160In fact, for the second use case, there is a more convenient method. You can
161add a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
162specifying which dependencies `nix-shell` needs. With the following shebang, you
163can just execute `./myscript.py`, and it will make available all dependencies and
164run the script in the `python3` shell.
165
166```py
167#! /usr/bin/env nix-shell
168#! nix-shell -i 'python3.withPackages(ps: [ps.numpy])'
169
170import numpy
171
172print(numpy.__version__)
173```
174
175### Developing with Python
176
177Now that you know how to get a working Python environment with Nix, it is time
178to go forward and start actually developing with Python. We will first have a
179look at how Python packages are packaged on Nix. Then, we will look at how you
180can use development mode with your code.
181
182#### Packaging a library
183
184With Nix all packages are built by functions. The main function in Nix for
185building Python libraries is `buildPythonPackage`. Let's see how we can build the
186`toolz` package.
187
188```nix
189{ # ...
190
191 toolz = buildPythonPackage rec {
192 pname = "toolz";
193 version = "0.7.4";
194 name = "${pname}-${version}";
195
196 src = fetchPypi {
197 inherit pname version;
198 sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
199 };
200
201 doCheck = false;
202
203 meta = {
204 homepage = "http://github.com/pytoolz/toolz/";
205 description = "List processing tools and functional utilities";
206 license = licenses.bsd3;
207 maintainers = with maintainers; [ fridh ];
208 };
209 };
210}
211```
212
213What happens here? The function `buildPythonPackage` is called and as argument
214it accepts a set. In this case the set is a recursive set, `rec`. One of the
215arguments is the name of the package, which consists of a basename (generally
216following the name on PyPi) and a version. Another argument, `src` specifies the
217source, which in this case is fetched from PyPI using the helper function
218`fetchPypi`. The argument `doCheck` is used to set whether tests should be run
219when building the package. Furthermore, we specify some (optional) meta
220information. The output of the function is a derivation.
221
222An expression for `toolz` can be found in the Nixpkgs repository. As explained
223in the introduction of this Python section, a derivation of `toolz` is available
224for each interpreter version, e.g. `python35.pkgs.toolz` refers to the `toolz`
225derivation corresponding to the CPython 3.5 interpreter.
226The above example works when you're directly working on
227`pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,
228you will want to test a Nix expression outside of the Nixpkgs tree.
229
230The following expression creates a derivation for the `toolz` package,
231and adds it along with a `numpy` package to a Python environment.
232
233```nix
234with import <nixpkgs> {};
235
236( let
237 my_toolz = python35.pkgs.buildPythonPackage rec {
238 pname = "toolz";
239 version = "0.7.4";
240 name = "${pname}-${version}";
241
242 src = python35.pkgs.fetchPypi {
243 inherit pname version;
244 sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
245 };
246
247 doCheck = false;
248
249 meta = {
250 homepage = "http://github.com/pytoolz/toolz/";
251 description = "List processing tools and functional utilities";
252 };
253 };
254
255 in python35.withPackages (ps: [ps.numpy my_toolz])
256).env
257```
258Executing `nix-shell` will result in an environment in which you can use
259Python 3.5 and the `toolz` package. As you can see we had to explicitly mention
260for which Python version we want to build a package.
261
262So, what did we do here? Well, we took the Nix expression that we used earlier
263to build a Python environment, and said that we wanted to include our own
264version of `toolz`, named `my_toolz`. To introduce our own package in the scope
265of `withPackages` we used a `let` expression. You can see that we used
266`ps.numpy` to select numpy from the nixpkgs package set (`ps`). We did not take
267`toolz` from the Nixpkgs package set this time, but instead took our own version
268that we introduced with the `let` expression.
269
270#### Handling dependencies
271
272Our example, `toolz`, does not have any dependencies on other Python
273packages or system libraries. According to the manual, `buildPythonPackage`
274uses the arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If something is
275exclusively a build-time dependency, then the dependency should be included as a
276`buildInput`, but if it is (also) a runtime dependency, then it should be added
277to `propagatedBuildInputs`. Test dependencies are considered build-time dependencies.
278
279The following example shows which arguments are given to `buildPythonPackage` in
280order to build [`datashape`](https://github.com/blaze/datashape).
281
282```nix
283{ # ...
284
285 datashape = buildPythonPackage rec {
286 name = "datashape-${version}";
287 version = "0.4.7";
288
289 src = pkgs.fetchurl {
290 url = "mirror://pypi/D/DataShape/${name}.tar.gz";
291 sha256 = "14b2ef766d4c9652ab813182e866f493475e65e558bed0822e38bf07bba1a278";
292 };
293
294 buildInputs = with self; [ pytest ];
295 propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
296
297 meta = {
298 homepage = https://github.com/ContinuumIO/datashape;
299 description = "A data description language";
300 license = licenses.bsd2;
301 maintainers = with maintainers; [ fridh ];
302 };
303 };
304}
305```
306
307We can see several runtime dependencies, `numpy`, `multipledispatch`, and
308`dateutil`. Furthermore, we have one `buildInput`, i.e. `pytest`. `pytest` is a
309test runner and is only used during the `checkPhase` and is therefore not added
310to `propagatedBuildInputs`.
311
312In the previous case we had only dependencies on other Python packages to consider.
313Occasionally you have also system libraries to consider. E.g., `lxml` provides
314Python bindings to `libxml2` and `libxslt`. These libraries are only required
315when building the bindings and are therefore added as `buildInputs`.
316
317```nix
318{ # ...
319
320 lxml = buildPythonPackage rec {
321 name = "lxml-3.4.4";
322
323 src = pkgs.fetchurl {
324 url = "mirror://pypi/l/lxml/${name}.tar.gz";
325 sha256 = "16a0fa97hym9ysdk3rmqz32xdjqmy4w34ld3rm3jf5viqjx65lxk";
326 };
327
328 buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
329
330 meta = {
331 description = "Pythonic binding for the libxml2 and libxslt libraries";
332 homepage = http://lxml.de;
333 license = licenses.bsd3;
334 maintainers = with maintainers; [ sjourdois ];
335 };
336 };
337}
338```
339
340In this example `lxml` and Nix are able to work out exactly where the relevant
341files of the dependencies are. This is not always the case.
342
343The example below shows bindings to The Fastest Fourier Transform in the West, commonly known as
344FFTW. On Nix we have separate packages of FFTW for the different types of floats
345(`"single"`, `"double"`, `"long-double"`). The bindings need all three types,
346and therefore we add all three as `buildInputs`. The bindings don't expect to
347find each of them in a different folder, and therefore we have to set `LDFLAGS`
348and `CFLAGS`.
349
350```nix
351{ # ...
352
353 pyfftw = buildPythonPackage rec {
354 name = "pyfftw-${version}";
355 version = "0.9.2";
356
357 src = pkgs.fetchurl {
358 url = "mirror://pypi/p/pyFFTW/pyFFTW-${version}.tar.gz";
359 sha256 = "f6bbb6afa93085409ab24885a1a3cdb8909f095a142f4d49e346f2bd1b789074";
360 };
361
362 buildInputs = [ pkgs.fftw pkgs.fftwFloat pkgs.fftwLongDouble];
363
364 propagatedBuildInputs = with self; [ numpy scipy ];
365
366 # Tests cannot import pyfftw. pyfftw works fine though.
367 doCheck = false;
368
369 preConfigure = ''
370 export LDFLAGS="-L${pkgs.fftw.dev}/lib -L${pkgs.fftwFloat.out}/lib -L${pkgs.fftwLongDouble.out}/lib"
371 export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include"
372 '';
373
374 meta = {
375 description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms";
376 homepage = http://hgomersall.github.com/pyFFTW/;
377 license = with licenses; [ bsd2 bsd3 ];
378 maintainer = with maintainers; [ fridh ];
379 };
380 };
381}
382```
383Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
384
385
386#### Develop local package
387
388As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode) (`python setup.py develop`);
389instead of installing the package this command creates a special link to the project code.
390That way, you can run updated code without having to reinstall after each and every change you make.
391Development mode is also available. Let's see how you can use it.
392
393In the previous Nix expression the source was fetched from an url. We can also refer to a local source instead using
394`src = ./path/to/source/tree;`
395
396If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
397is a local source, and if the local source has a `setup.py`, then development
398mode is activated.
399
400In the following example we create a simple environment that
401has a Python 3.5 version of our package in it, as well as its dependencies and
402other packages we like to have in the environment, all specified with `propagatedBuildInputs`.
403Indeed, we can just add any package we like to have in our environment to `propagatedBuildInputs`.
404
405```nix
406with import <nixpkgs> {};
407with pkgs.python35Packages;
408
409buildPythonPackage rec {
410 name = "mypackage";
411 src = ./path/to/package/source;
412 propagatedBuildInputs = [ pytest numpy pkgs.libsndfile ];
413}
414```
415
416It is important to note that due to how development mode is implemented on Nix it is not possible to have multiple packages simultaneously in development mode.
417
418
419### Organising your packages
420
421So far we discussed how you can use Python on Nix, and how you can develop with
422it. We've looked at how you write expressions to package Python packages, and we
423looked at how you can create environments in which specified packages are
424available.
425
426At some point you'll likely have multiple packages which you would
427like to be able to use in different projects. In order to minimise unnecessary
428duplication we now look at how you can maintain yourself a repository with your
429own packages. The important functions here are `import` and `callPackage`.
430
431### Including a derivation using `callPackage`
432
433Earlier we created a Python environment using `withPackages`, and included the
434`toolz` package via a `let` expression.
435Let's split the package definition from the environment definition.
436
437We first create a function that builds `toolz` in `~/path/to/toolz/release.nix`
438
439```nix
440{ pkgs, buildPythonPackage }:
441
442buildPythonPackage rec {
443 name = "toolz-${version}";
444 version = "0.7.4";
445
446 src = pkgs.fetchurl {
447 url = "mirror://pypi/t/toolz/toolz-${version}.tar.gz";
448 sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
449 };
450
451 meta = {
452 homepage = "http://github.com/pytoolz/toolz/";
453 description = "List processing tools and functional utilities";
454 license = licenses.bsd3;
455 maintainers = with maintainers; [ fridh ];
456 };
457}
458```
459
460It takes two arguments, `pkgs` and `buildPythonPackage`.
461We now call this function using `callPackage` in the definition of our environment
462
463```nix
464with import <nixpkgs> {};
465
466( let
467 toolz = pkgs.callPackage /path/to/toolz/release.nix {
468 pkgs = pkgs;
469 buildPythonPackage = pkgs.python35Packages.buildPythonPackage;
470 };
471 in pkgs.python35.withPackages (ps: [ ps.numpy toolz ])
472).env
473```
474
475Important to remember is that the Python version for which the package is made
476depends on the `python` derivation that is passed to `buildPythonPackage`. Nix
477tries to automatically pass arguments when possible, which is why generally you
478don't explicitly define which `python` derivation should be used. In the above
479example we use `buildPythonPackage` that is part of the set `python35Packages`,
480and in this case the `python35` interpreter is automatically used.
481
482
483
484## Reference
485
486### Interpreters
487
488Versions 2.7, 3.3, 3.4, 3.5 and 3.6 of the CPython interpreter are available as
489respectively `python27`, `python34`, `python35` and `python36`. The PyPy interpreter
490is available as `pypy`. The aliases `python2` and `python3` correspond to respectively `python27` and
491`python35`. The default interpreter, `python`, maps to `python2`.
492The Nix expressions for the interpreters can be found in
493`pkgs/development/interpreters/python`.
494
495All packages depending on any Python interpreter get appended
496`out/{python.sitePackages}` to `$PYTHONPATH` if such directory
497exists.
498
499#### Missing `tkinter` module standard library
500
501To reduce closure size the `Tkinter`/`tkinter` is available as a separate package, `pythonPackages.tkinter`.
502
503#### Attributes on interpreters packages
504
505Each interpreter has the following attributes:
506
507- `libPrefix`. Name of the folder in `${python}/lib/` for corresponding interpreter.
508- `interpreter`. Alias for `${python}/bin/${executable}`.
509- `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
510- `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
511- `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
512- `executable`. Name of the interpreter executable, e.g. `python3.4`.
513- `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
514
515### Building packages and applications
516
517Python libraries and applications that use `setuptools` or
518`distutils` are typically build with respectively the `buildPythonPackage` and
519`buildPythonApplication` functions. These two functions also support installing a `wheel`.
520
521All Python packages reside in `pkgs/top-level/python-packages.nix` and all
522applications elsewhere. In case a package is used as both a library and an application,
523then the package should be in `pkgs/top-level/python-packages.nix` since only those packages are made
524available for all interpreter versions. The preferred location for library expressions is in
525`pkgs/development/python-modules`. It is important that these packages are
526called from `pkgs/top-level/python-packages.nix` and not elsewhere, to guarantee
527the right version of the package is built.
528
529Based on the packages defined in `pkgs/top-level/python-packages.nix` an
530attribute set is created for each available Python interpreter. The available
531sets are
532
533* `pkgs.python26Packages`
534* `pkgs.python27Packages`
535* `pkgs.python34Packages`
536* `pkgs.python35Packages`
537* `pkgs.python36Packages`
538* `pkgs.pypyPackages`
539
540and the aliases
541
542* `pkgs.python2Packages` pointing to `pkgs.python27Packages`
543* `pkgs.python3Packages` pointing to `pkgs.python35Packages`
544* `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
545
546#### `buildPythonPackage` function
547
548The `buildPythonPackage` function is implemented in
549`pkgs/development/interpreters/python/build-python-package.nix`
550
551The following is an example:
552```nix
553{ # ...
554
555 twisted = buildPythonPackage {
556 name = "twisted-8.1.0";
557
558 src = pkgs.fetchurl {
559 url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
560 sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
561 };
562
563 propagatedBuildInputs = [ self.ZopeInterface ];
564
565 meta = {
566 homepage = http://twistedmatrix.com/;
567 description = "Twisted, an event-driven networking engine written in Python";
568 license = stdenv.lib.licenses.mit;
569 };
570 };
571}
572```
573
574The `buildPythonPackage` mainly does four things:
575
576* In the `buildPhase`, it calls `${python.interpreter} setup.py bdist_wheel` to
577 build a wheel binary zipfile.
578* In the `installPhase`, it installs the wheel file using `pip install *.whl`.
579* In the `postFixup` phase, the `wrapPythonPrograms` bash function is called to
580 wrap all programs in the `$out/bin/*` directory to include `$PATH`
581 environment variable and add dependent libraries to script's `sys.path`.
582* In the `installCheck` phase, `${python.interpreter} setup.py test` is ran.
583
584As in Perl, dependencies on other Python packages can be specified in the
585`buildInputs` and `propagatedBuildInputs` attributes. If something is
586exclusively a build-time dependency, use `buildInputs`; if it’s (also) a runtime
587dependency, use `propagatedBuildInputs`.
588
589By default tests are run because `doCheck = true`. Test dependencies, like
590e.g. the test runner, should be added to `buildInputs`.
591
592By default `meta.platforms` is set to the same value
593as the interpreter unless overriden otherwise.
594
595##### `buildPythonPackage` parameters
596
597All parameters from `mkDerivation` function are still supported.
598
599* `namePrefix`: Prepended text to `${name}` parameter. Defaults to `"python3.3-"` for Python 3.3, etc. Set it to `""` if you're packaging an application or a command line tool.
600* `disabled`: If `true`, package is not build for particular python interpreter version. Grep around `pkgs/top-level/python-packages.nix` for examples.
601* `setupPyBuildFlags`: List of flags passed to `setup.py build_ext` command.
602* `pythonPath`: List of packages to be added into `$PYTHONPATH`. Packages in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
603* `preShellHook`: Hook to execute commands before `shellHook`.
604* `postShellHook`: Hook to execute commands after `shellHook`.
605* `makeWrapperArgs`: A list of strings. Arguments to be passed to `makeWrapper`, which wraps generated binaries. By default, the arguments to `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling the binary. Additional arguments here can allow a developer to set environment variables which will be available when the binary is run. For example, `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
606* `installFlags`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"].
607* `format`: Format of the source. Valid options are `setuptools` (default), `flit`, `wheel`, and `other`. `setuptools` is for when the source has a `setup.py` and `setuptools` is used to build a wheel, `flit`, in case `flit` should be used to build a wheel, and `wheel` in case a wheel is provided. In case you need to provide your own `buildPhase` and `installPhase` you can use `other`.
608* `catchConflicts` If `true`, abort package build if a package name appears more than once in dependency tree. Default is `true`.
609* `checkInputs` Dependencies needed for running the `checkPhase`. These are added to `buildInputs` when `doCheck = true`.
610
611##### Overriding Python packages
612
613The `buildPythonPackage` function has a `overridePythonAttrs` method that
614can be used to override the package. In the following example we create an
615environment where we have the `blaze` package using an older version of `pandas`.
616We override first the Python interpreter and pass
617`packageOverrides` which contains the overrides for packages in the package set.
618
619```nix
620with import <nixpkgs> {};
621
622(let
623 python = let
624 packageOverrides = self: super: {
625 pandas = super.pandas.overridePythonAttrs(old: rec {
626 version = "0.19.1";
627 name = "pandas-${version}";
628 src = super.fetchPypi {
629 pname = "pandas";
630 inherit version;
631 sha256 = "08blshqj9zj1wyjhhw3kl2vas75vhhicvv72flvf1z3jvapgw295";
632 };
633 });
634 };
635 in pkgs.python3.override {inherit packageOverrides;};
636
637in python.withPackages(ps: [ps.blaze])).env
638```
639
640#### `buildPythonApplication` function
641
642The `buildPythonApplication` function is practically the same as `buildPythonPackage`.
643The difference is that `buildPythonPackage` by default prefixes the names of the packages with the version of the interpreter.
644Because with an application we're not interested in multiple version the prefix is dropped.
645
646#### python.buildEnv function
647
648Python environments can be created using the low-level `pkgs.buildEnv` function.
649This example shows how to create an environment that has the Pyramid Web Framework.
650Saving the following as `default.nix`
651```nix
652with import <nixpkgs> {};
653
654python.buildEnv.override {
655 extraLibs = [ pkgs.pythonPackages.pyramid ];
656 ignoreCollisions = true;
657}
658```
659
660and running `nix-build` will create
661```
662/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
663```
664
665with wrapped binaries in `bin/`.
666
667You can also use the `env` attribute to create local environments with needed
668packages installed. This is somewhat comparable to `virtualenv`. For example,
669running `nix-shell` with the following `shell.nix`
670```nix
671with import <nixpkgs> {};
672
673(python3.buildEnv.override {
674 extraLibs = with python3Packages; [ numpy requests ];
675}).env
676```
677
678will drop you into a shell where Python will have the
679specified packages in its path.
680
681
682##### `python.buildEnv` arguments
683
684* `extraLibs`: List of packages installed inside the environment.
685* `postBuild`: Shell command executed after the build of environment.
686* `ignoreCollisions`: Ignore file collisions inside the environment (default is `false`).
687
688#### python.withPackages function
689
690The `python.withPackages` function provides a simpler interface to the `python.buildEnv` functionality.
691It takes a function as an argument that is passed the set of python packages and returns the list
692of the packages to be included in the environment. Using the `withPackages` function, the previous
693example for the Pyramid Web Framework environment can be written like this:
694```nix
695with import <nixpkgs> {};
696
697python.withPackages (ps: [ps.pyramid])
698```
699
700`withPackages` passes the correct package set for the specific interpreter version as an
701argument to the function. In the above example, `ps` equals `pythonPackages`.
702But you can also easily switch to using python3:
703```nix
704with import <nixpkgs> {};
705
706python3.withPackages (ps: [ps.pyramid])
707```
708
709Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
710
711As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
712attribute. The `shell.nix` file from the previous section can thus be also written like this:
713```nix
714with import <nixpkgs> {};
715
716(python36.withPackages (ps: [ps.numpy ps.requests])).env
717```
718
719In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
720such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
721
722Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv`
723should be used with `ignoreCollisions = true`.
724
725### Development mode
726
727Development or editable mode is supported. To develop Python packages
728`buildPythonPackage` has additional logic inside `shellPhase` to run `pip
729install -e . --prefix $TMPDIR/`for the package.
730
731Warning: `shellPhase` is executed only if `setup.py` exists.
732
733Given a `default.nix`:
734```nix
735with import <nixpkgs> {};
736
737buildPythonPackage { name = "myproject";
738
739buildInputs = with pkgs.pythonPackages; [ pyramid ];
740
741src = ./.; }
742```
743
744Running `nix-shell` with no arguments should give you
745the environment in which the package would be built with
746`nix-build`.
747
748Shortcut to setup environments with C headers/libraries and python packages:
749```shell
750nix-shell -p pythonPackages.pyramid zlib libjpeg git
751```
752
753Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is invoked.
754
755### Tools
756
757Packages inside nixpkgs are written by hand. However many tools exist in
758community to help save time. No tool is preferred at the moment.
759
760- [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov
761- [pypi2nix](https://github.com/garbas/pypi2nix) by Rok Garbas
762- [pypi2nix](https://github.com/offlinehacker/pypi2nix) by Jaka Hudoklin
763
764### Deterministic builds
765
766Python 2.7, 3.5 and 3.6 are now built deterministically and 3.4 mostly.
767Minor modifications had to be made to the interpreters in order to generate
768deterministic bytecode. This has security implications and is relevant for
769those using Python in a `nix-shell`.
770
771When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will have timestamp 1.
772The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1` and
773[PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
774Both are also exported in `nix-shell`.
775
776
777## FAQ
778
779### How to solve circular dependencies?
780
781Consider the packages `A` and `B` that depend on each other. When packaging `B`,
782a solution is to override package `A` not to depend on `B` as an input. The same
783should also be done when packaging `A`.
784
785### How to override a Python package?
786
787We can override the interpreter and pass `packageOverrides`.
788In the following example we rename the `pandas` package and build it.
789```nix
790with import <nixpkgs> {};
791
792(let
793 python = let
794 packageOverrides = self: super: {
795 pandas = super.pandas.overridePythonAttrs(old: {name="foo";});
796 };
797 in pkgs.python35.override {inherit packageOverrides;};
798
799in python.withPackages(ps: [ps.pandas])).env
800```
801Using `nix-build` on this expression will build an environment that contains the
802package `pandas` but with the new name `foo`.
803
804All packages in the package set will use the renamed package.
805A typical use case is to switch to another version of a certain package.
806For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
807In the following example we use a different version of `scipy` and create an environment that uses it.
808All packages in the Python package set will now use the updated `scipy` version.
809
810```nix
811with import <nixpkgs> {};
812
813( let
814 packageOverrides = self: super: {
815 scipy = super.scipy_0_17;
816 };
817 in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
818).env
819```
820The requested package `blaze` depends on `pandas` which itself depends on `scipy`.
821
822If you want the whole of Nixpkgs to use your modifications, then you can use `overlays`
823as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`.
824```nix
825let
826 pkgs = import <nixpkgs> {};
827 newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: {
828 python27 = let
829 packageOverrides = self: super: {
830 numpy = super.numpy_1_10;
831 };
832 in pkgssuper.python27.override {inherit packageOverrides;};
833 } ) ]; };
834in newpkgs.inkscape
835```
836
837### `python setup.py bdist_wheel` cannot create .whl
838
839Executing `python setup.py bdist_wheel` in a `nix-shell `fails with
840```
841ValueError: ZIP does not support timestamps before 1980
842```
843This is because files are included that depend on items in the Nix store which have a timestamp of, that is, it corresponds to January the 1st, 1970 at 00:00:00. And as the error informs you, ZIP does not support that.
844The command `bdist_wheel` takes into account `SOURCE_DATE_EPOCH`, and `nix-shell` sets this to 1. By setting it to a value corresponding to 1980 or later, or by unsetting it, it is possible to build wheels.
845
846Use 1980 as timestamp:
847```shell
848nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel"
849```
850or the current time:
851```shell
852nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel"
853```
854or unset:
855```shell
856nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
857```
858
859### `install_data` / `data_files` problems
860
861If you get the following error:
862```
863could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc':
864Permission denied
865```
866This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`.
867Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
868As workaround install it as an extra `preInstall` step:
869```shell
870${python.interpreter} setup.py install_data --install-dir=$out --root=$out
871sed -i '/ = data\_files/d' setup.py
872```
873
874### Rationale of non-existent global site-packages
875
876On most operating systems a global `site-packages` is maintained. This however
877becomes problematic if you want to run multiple Python versions or have multiple
878versions of certain libraries for your projects. Generally, you would solve such
879issues by creating virtual environments using `virtualenv`.
880
881On Nix each package has an isolated dependency tree which, in the case of
882Python, guarantees the right versions of the interpreter and libraries or
883packages are available. There is therefore no need to maintain a global `site-packages`.
884
885If you want to create a Python environment for development, then the recommended
886method is to use `nix-shell`, either with or without the `python.buildEnv`
887function.
888
889### How to consume python modules using pip in a virtualenv like I am used to on other Operating Systems ?
890
891This is an example of a `default.nix` for a `nix-shell`, which allows to consume a `virtualenv` environment,
892and install python modules through `pip` the traditional way.
893
894Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
895
896```nix
897with import <nixpkgs> {};
898with pkgs.python27Packages;
899
900stdenv.mkDerivation {
901 name = "impurePythonEnv";
902 buildInputs = [
903 # these packages are required for virtualenv and pip to work:
904 #
905 python27Full
906 python27Packages.virtualenv
907 python27Packages.pip
908 # the following packages are related to the dependencies of your python
909 # project.
910 # In this particular example the python modules listed in the
911 # requirements.tx require the following packages to be installed locally
912 # in order to compile any binary extensions they may require.
913 #
914 taglib
915 openssl
916 git
917 libxml2
918 libxslt
919 libzip
920 stdenv
921 zlib ];
922 src = null;
923 shellHook = ''
924 # set SOURCE_DATE_EPOCH so that we can use python wheels
925 SOURCE_DATE_EPOCH=$(date +%s)
926 virtualenv --no-setuptools venv
927 export PATH=$PWD/venv/bin:$PATH
928 pip install -r requirements.txt
929 '';
930}
931```
932
933Note that the `pip install` is an imperative action. So every time `nix-shell`
934is executed it will attempt to download the python modules listed in
935requirements.txt. However these will be cached locally within the `virtualenv`
936folder and not downloaded again.
937
938### How to override a Python package from `configuration.nix`?
939
940If you need to change a package's attribute(s) from `configuration.nix` you could do:
941
942```nix
943 nixpkgs.config.packageOverrides = superP: {
944 pythonPackages = superP.pythonPackages.override {
945 overrides = self: super: {
946 bepasty-server = super.bepasty-server.overrideAttrs ( oldAttrs: {
947 src = pkgs.fetchgit {
948 url = "https://github.com/bepasty/bepasty-server";
949 sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
950 rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
951 };
952 });
953 };
954 };
955 };
956```
957
958If you are using the `bepasty-server` package somewhere, for example in `systemPackages` or indirectly from `services.bepasty`, then a `nixos-rebuild switch` will rebuild the system but with the `bepasty-server` package using a different `src` attribute. This way one can modify `python` based software/libraries easily. Using `self` and `super` one can also alter dependencies (`buildInputs`) between the old state (`self`) and new state (`super`).
959
960### How to override a Python package using overlays?
961
962To alter a python package using overlays, you would use the following approach:
963
964```nix
965self: super:
966rec {
967 python = super.python.override {
968 packageOverrides = python-self: python-super: {
969 bepasty-server = python-super.bepasty-server.overrideAttrs ( oldAttrs: {
970 src = self.pkgs.fetchgit {
971 url = "https://github.com/bepasty/bepasty-server";
972 sha256 = "9ziqshmsf0rjvdhhca55sm0x8jz76fsf2q4rwh4m6lpcf8wr0nps";
973 rev = "e2516e8cf4f2afb5185337073607eb9e84a61d2d";
974 };
975 });
976 };
977 };
978 pythonPackages = python.pkgs;
979}
980```
981
982## Contributing
983
984### Contributing guidelines
985
986Following rules are desired to be respected:
987
988* Python libraries are supposed to be called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules/<name>/default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts.
989* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`.
990* Make sure libraries build for all Python interpreters.
991* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why.
992* Commit names of Python libraries should include `pythonPackages`, for example `pythonPackages.numpy: 1.11 -> 1.12`.