poetry2nix

To turn a Poetry project into a Nix package without using Flakes, create a default.nix file in your project root (next to pyproject.toml and poetry.lock). This method typically assumes you are using the niv tool to pin nixpkgs and poetry2nix.

Steps:

1. Initialize dependencies with niv:

   nix-shell -p niv
   niv init
   niv add nix-community/poetry2nix

2. Create default.nix: Use poetry2nix.mkPoetryApplication to define your package.
3. Build the application:

   nix-build default.nix

4. Run the application: The executable will be located in the ./result/bin/ directory. Replace <script> with the name defined in your [tool.poetry.scripts] section in pyproject.toml.

# file: default.nix
let
  sources = import ./nix/sources.nix;
  pkgs = import sources.nixpkgs { };
  # Let all API attributes like "poetry2nix.mkPoetryApplication"
  # use the packages and versions (python3, poetry etc.) from our pinned nixpkgs above
  # under the hood:
  poetry2nix = import sources.poetry2nix { inherit pkgs; };
  myPythonApp = poetry2nix.mkPoetryApplication { projectDir = ./.; };
in
myPythonApp

If you use Nix Flakes, you can import poetry2nix directly as an input. This approach allows you to use the poetry2nix.lib.mkPoetry2Nix helper to create a custom mkPoetryApplication function that uses the specific versions of Python and Poetry pinned in your nixpkgs input.

Steps:

1. Create flake.nix using the pattern below.
2. Run the application:

   nix run .

Using Templates:

To start a new project with a pre-configured flake template, run:

nix flake init --template github:nix-community/poetry2nix

# file: flake.nix
{
  description = "Python application packaged using poetry2nix";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.poetry2nix.url = "github:nix-community/poetry2nix";

  outputs = { self, nixpkgs, poetry2nix }: 
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
      # create a custom "mkPoetryApplication" API function that under the hood uses
      # the packages and versions (python3, poetry etc.) from our pinned nixpkgs above:
      inherit (poetry2nix.lib.mkPoetry2Nix { inherit pkgs; }) mkPoetryApplication;
      myPythonApp = mkPoetryApplication { projectDir = ./.; };
    in
    {
      apps.${system}.default = {
        type = "app";
        # replace <script> with the name in the [tool.poetry.scripts] section of your pyproject.toml
        program = "${myPythonApp}/bin/<script>";
      };
    };
}

If you encounter a ModuleNotFoundError: No module named 'PACKAGENAME' during build, it usually means a Python dependency requires a specific build tool (like setuptools, pdm, or flit) that isn't present in its build environment. Since poetry2nix prefers building from source, you must explicitly add the missing tool to the package's buildInputs using overridePythonAttrs within the overrides attribute of mkPoetryApplication.

Key details:

• Package names are normalized according to PEP-517 (e.g., flit_scm becomes flit-scm).
• You can use the short name (e.g., setuptools) instead of the full path (e.g., python39Packages.setuptools).
• If you have multiple overrides, you can chain them or use a mapping pattern to reduce repetition.

poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.defaultPoetryOverrides.extend
    (final: prev: {
      django-floppyforms = prev.django-floppyforms.overridePythonAttrs
      (
        old: {
          buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
        }
      );
    });
}

To use private repositories (e.g., via [[tool.poetry.source]] in pyproject.toml), poetry2nix requires a NETRC file for authentication. Follow these three steps:

1. Create a .netrc file: Place it in your home directory (~/.netrc) or a central location like /etc/nix/netrc.

   machine https://example.org
   login <repository-username>
   password <repository-password-or-token>

2. Mount the file into the Nix sandbox: Use the extra-sandbox-paths option so the build process can access the file.

   • Recommended (Per-build): Pass it directly in the terminal to avoid exposing secrets to all builds.
   • Global (Not recommended): Add to /etc/nix/nix.conf via extra-sandbox-paths /etc/nix/netrc.

   Note: You must be a trusted-user in your Nix configuration for this to work.

3. Pass the NETRC environment variable: Tell poetry2nix where the file is located inside the sandbox.

   • For Flakes: You must add the NETRC environment variable to the nix-daemon service (e.g., via systemd on NixOS).
   • For Non-Flake projects: Use a fake Nix search path -I NETRC=<path> in your command.

Important: Using impureEnvVars in attributes does not work for this purpose.

# For non-flake projects
nix-build -I NETRC=/etc/nix/netrc --option extra-sandbox-paths /etc/nix/netrc default.nix

# For flake projects
nix build . --extra-sandbox-paths /etc/nix/netrc

You can create a custom instance of poetry2nix using overrideScope. This is useful for injecting custom defaultPoetryOverrides globally for your project.

Using overrideScope in a Nix expression:

let
  p2nix = poetry2nix.overrideScope (final: prev: {
    defaultPoetryOverrides = prev.defaultPoetryOverrides.extend (pyfinal: pyprev: {
      my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });
    });
  });
in
  p2nix.mkPoetryApplication {
    projectDir = ./.;
  }

Using as a Nixpkgs Overlay:

let
  pkgs = import <nixpkgs> {
    overlays = [
      (final: prev: {
        poetry2nix = prev.poetry2nix.overrideScope (p2nixfinal: p2nixprev: {
          defaultPoetryOverrides = p2nixprev.defaultPoetryOverrides.extend (pyfinal: pyprev: {
            my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });
          });
        });
      })
    ];
  };
in 
  pkgs.poetry2nix.mkPoetryApplication { projectDir = ./.; }