poetry2nix turns Poetry projects into Nix derivations without the need to actually write Nix expressions. It does so by parsing pyproject.toml and poetry.lock and converting them to Nix derivations on the fly.

For more information, see the announcement post on the Tweag blog.

• API
• How-to guides
• Using the flake
• Contributing
• Contact
• Acknowledgements
• License

The poetry2nix public API consists of the following attributes:

• mkPoetryApplication: Creates a Python application.
• mkPoetryEnv: Creates a Python environment with an interpreter and all packages from poetry.lock.
• mkPoetryPackages: Creates an attribute set providing access to the generated packages and other artifacts.
• mkPoetryScriptsPackage: Creates a package containing the scripts from tool.poetry.scripts of the pyproject.toml.
• mkPoetryEditablePackage: Creates a package containing editable sources. Changes in the specified paths will be reflected in an interactive nix-shell session without the need to restart it.
• defaultPoetryOverrides: A set of bundled overrides fixing problems with Python packages.
• overrides.withDefaults: A convenience function for specifying overrides on top of the defaults.
• overrides.withoutDefaults: A convenience function for specifying overrides without defaults.
• cleanPythonSources: A function to create a source filter for python projects.

Creates a Python application using the Python interpreter specified based on the designated poetry project and lock files. mkPoetryApplication takes an attribute set with the following attributes (attributes without default are mandatory):

• projectDir: path to the root of the project.
• src: project source (default: cleanPythonSources { src = projectDir; }).
• pyproject: path to pyproject.toml (default: projectDir + "/pyproject.toml").
• poetrylock: poetry.lock file path (default: projectDir + "/poetry.lock").
• overrides: Python overrides to apply (default: [defaultPoetryOverrides]).
• meta: application meta data (default: {}).
• python: The Python interpreter to use (default: pkgs.python3).
• preferWheels : Use wheels rather than sdist as much as possible (default: false).
• groups: Which Poetry 1.2.0+ dependency groups to install (default: [ ]).

Other attributes are passed through to buildPythonApplication.

poetry2nix.mkPoetryApplication {
    projectDir = ./.;
}

See ./pkgs/poetry/default.nix for a working example.

The resulting derivation also has the passthru attribute dependencyEnv, which is an environment with a python interpreter, all non-development dependencies and your application. This can be used if your application doesn't provide any binaries on its own and instead relies on dependencies binaries to call its modules (as is often the case with celery or gunicorn). For example, if your application defines a CLI for the module admin and a gunicorn app for the module web, a working default.nix would contain

let
    app = poetry2nix.mkPoetryApplication {
        projectDir = ./.;
    };
in app.dependencyEnv

After building this expression, your CLI and app can be called with these commands

$ result/bin/python -m admin
$ result/bin/gunicorn web:app

Note: If you need to perform overrides on the application, use app.dependencyEnv.override { app = app.override { ... }; }. See ./tests/dependency-environment/default.nix for a full example.

Creates an environment that provides a Python interpreter along with all dependencies declared by the designated poetry project and lock files. Also allows package sources of an application to be installed in editable mode for fast development. mkPoetryEnv takes an attribute set with the following attributes (attributes without default are mandatory):

• projectDir: path to the root of the project.
• pyproject: path to pyproject.toml (default: projectDir + "/pyproject.toml").
• poetrylock: poetry.lock file path (default: projectDir + "/poetry.lock").
• overrides: Python overrides to apply (default: [defaultPoetryOverrides]).
• python: The Python interpreter to use (default: pkgs.python3).
• editablePackageSources: A mapping from package name to source directory, these will be installed in editable mode. Note that path dependencies with develop = true will be installed in editable mode unless explicitly passed to editablePackageSources as null. (default: {}).
• extraPackages: A function taking a Python package set and returning a list of extra packages to include in the environment. This is intended for packages deliberately not added to pyproject.toml that you still want to include. An example of such a package may be pip. (default: (ps: [ ])).
• preferWheels : Use wheels rather than sdist as much as possible (default: false).
• groups: Which Poetry 1.2.0+ dependency groups to install (default: [ "dev" ]).

poetry2nix.mkPoetryEnv {
    projectDir = ./.;
}

See ./tests/env/default.nix for a working example.

poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
        my-app = ./src;
    };
}

See ./tests/editable/default.nix for a working example of an editable package.

The env attribute of the attribute set created by mkPoetryEnv contains a shell environment.

{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env

For a shell environment including external dependencies, override the env to add dependency packages (for example, pkgs.hello) as build inputs.

{ pkgs ? import <nixpkgs> {}