nox-poetry

What it is and what it does

nox-poetry is a drop-in replacement for Nox's @session decorator and Session object that makes Nox respect Poetry's lock file when installing packages. Instead of letting pip resolve dependencies fresh each time, it exports Poetry's constraints and uses them to pin versions during installation, ensuring reproducible and deterministic test runs across environments and CI systems.

The package works by intercepting session.install() calls and passing them through Poetry's export mechanism, which generates a constraints file that pip then uses. When you install your own package (via session.install(".")), nox-poetry builds a wheel using Poetry first, then installs that wheel. This approach avoids the pitfalls of editable installs while keeping each session's environment minimal—you only get the dependencies each tool actually needs.

Use it for:

• Run tests across Python versions with dependencies pinned by Poetry's lock file, ensuring CI and local results match.
• Install development tools as Poetry dev dependencies and use them in isolated Nox sessions without the full dependency tree.
• Build and test a wheel installation in Nox rather than an editable install, catching packaging mistakes before release.
• Manage reproducible checks across a team by centralizing dependency versions in Poetry's lock file.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Integrates Poetry's lock file into Nox sessions, allowing session.install() to install packages at versions pinned by Poetry rather than resolving them fresh each time.

Yes. If you use both Poetry and Nox, this package solves a real problem—making Nox respect your lock file so that session dependencies are reproducible and deterministic. Low install friction, active maintenance, no known vulnerabilities, and permissive license. The only gotcha is the installation requirement (must be in the same environment as Nox, and Poetry >= 1.0.0 must be on your system), which is documented and straightforward.

Install

nox-poetry on PyPI

pip install nox-poetry

uv add nox-poetry

poetry add nox-poetry

Installing nox-poetry

Before you install

Low friction: pure Python wheel with four straightforward runtime dependencies (build, nox, packaging, tomlkit). Must be installed into the same environment as Nox itself—if using pipx for Nox, inject it via pipx inject rather than pip install. Active maintenance with recent release.

License in practice

MIT permissive license; you can use, modify, and distribute this package freely in commercial and private projects without restriction.

Quickstart

pip install nox-poetry

from nox_poetry import session

@session(python=["3.10", "3.9"])
def tests(session):
    session.install("pytest", ".")
    session.run("pytest")

Requires Poetry >= 1.0.0 installed on your system and Python >= 3.9. In Poetry >= 2, poetry-plugin-export must be declared as a required plugin in pyproject.toml.

Verify before relying

• Whether session.poetry utilities (installroot, build_package, export_requirements) are stable or subject to breaking changes.
• Performance impact of Poetry export and wheel-building on session startup time for large projects.

Package facts

Evidence: nox_poetry-1.2.0-py3-none-any.whl

Tags

More Build Tools packages