Nox-Poetry Integration

1.2.0 · active · verified Thu Apr 16

nox-poetry is a plugin for Nox, a flexible test automation tool, that simplifies testing and building Python projects managed with Poetry. It integrates Poetry's dependency management and build processes directly into Nox sessions, providing features like installing project dependencies, building packages, and exporting requirements. The current version is 1.2.0, with regular updates that often include support for newer Python and Poetry versions, alongside bug fixes and minor feature enhancements.

Common errors

```
AttributeError: 'Session' object has no attribute 'poetry'
```
cause `nox-poetry` is not installed in the Nox environment where the `noxfile.py` is being run, or it's not being properly integrated by Nox.

fix Ensure `nox-poetry` is listed in your `noxfile.py`'s `session.install()` calls (e.g., `session.install('nox-poetry')`) or globally installed in the Nox execution environment. Also, verify `import nox` is present and sessions are decorated with `@nox.session`.
```
ModuleNotFoundError: No module named 'nox_poetry.core'
```
cause Attempting to import a module (e.g., `nox_poetry.core`) that was removed in `nox-poetry` v1.0.0 due to API refactoring.

fix Refactor your `noxfile.py` to use `session.poetry` methods directly instead of importing from removed modules. For example, replace `from nox_poetry.core import build_package` with `session.poetry.build()`.
```
nox-poetry requires poetry to be installed and available in the session.
```
cause The `poetry` executable could not be found within the Nox session's PATH.

fix If `poetry` is not globally installed, you can add `session.install('poetry')` to your session before calling `session.poetry.*` commands. Alternatively, ensure `poetry` is available in the shell where Nox is invoked.
```
ValueError: The project root directory could not be determined. Please ensure that a pyproject.toml file (or another supported project file) is present in the current directory or a parent directory.
```
cause `nox-poetry` could not locate your project's `pyproject.toml` file, which is essential for Poetry-based projects.

fix Ensure you are running Nox from your project's root directory, or explicitly specify the project root if using advanced Nox configurations. Verify your `pyproject.toml` file exists and is correctly structured for Poetry.

Warnings

breaking Breaking API change in v1.0.0: Global helper functions like `export_requirements`, `build_package`, `patch`, `install`, `installroot` and modules like `core`, `patch` were removed. All functionality is now accessed through the `session.poetry` object.
Fix: Migrate calls from global functions (e.g., `build_package()`) to `session.poetry` methods (e.g., `session.poetry.build()`). Refer to the official documentation for updated usage patterns.
breaking Dropped support for Python 3.8 in v1.2.0. Projects using `nox-poetry` 1.2.0 or newer must use Python 3.9 or higher for their Nox environments.
Fix: Ensure your Nox sessions are configured to use Python >=3.9. Update your `noxfile.py`'s `python` parameter in `@nox.session` decorators accordingly. For example, `python=['3.9', '3.10']`.
breaking Dropped support for Python 3.7 in v1.1.0. Projects using `nox-poetry` 1.1.0 or newer must use Python 3.8 or higher for their Nox environments.
Fix: Ensure your Nox sessions are configured to use Python >=3.8. Update your `noxfile.py`'s `python` parameter in `@nox.session` decorators.
gotcha `nox-poetry` requires `poetry` to be installed and available in the session's PATH. If `poetry` is not found, `session.poetry` commands will fail with an error like 'nox-poetry requires poetry to be installed'.
Fix: Ensure `poetry` is installed in the environment where Nox is run, or if preferred, install `poetry` within the Nox session itself using `session.install('poetry')` *before* calling `session.poetry.*` methods.
gotcha `nox-poetry` expects a `pyproject.toml` file at the root of your project with a valid `[tool.poetry]` section for package metadata and dependency management. Incorrect or missing configuration will lead to errors like 'ValueError: The project root directory could not be determined'.
Fix: Verify your `pyproject.toml` correctly defines your project using Poetry's specification. Ensure it's in the project root where Nox is executed.

Install

pip install nox-poetry Install nox-poetry

Imports

session.poetry
wrong:
```
from nox_poetry.core import build_package
```
correct:
```
# noxfile.py
import nox

@nox.session
def tests(session):
    session.poetry.install(groups=["dev"])
    session.run("pytest")
```
Global functions and modules (e.g., `build_package`, `export_requirements`, `core` module) were deprecated in v0.8.0 and removed in v1.0.0. Use `session.poetry.*` methods instead.

Quickstart

This `noxfile.py` demonstrates how to use `nox-poetry` to manage dependencies and run tests for a Poetry-managed project across multiple Python versions, and how to build the project.

# noxfile.py
import nox

@nox.session(python=["3.9", "3.10", "3.11", "3.12"])
def tests(session):
    # Install project dependencies, including dev dependencies.
    # This respects the poetry.lock file.
    session.poetry.install(extras=["all"], groups=["dev"])

    # Run tests
    session.run("pytest", *session.posargs)

@nox.session(python="3.12")
def build(session):
    # Build the package (sdist and wheel)
    session.poetry.build()
    # You can then use the built package, e.g., check its contents
    session.run("ls", "dist", external=True)

view raw JSON →