Poetry Multiproject Plugin

1.8.4 verified Fri May 01 auth: no python

A Poetry plugin that enables using relative package includes in multi-project monorepos. It allows a Poetry project to include packages from sibling directories as if they were part of the same project, with support for Poetry v2 and PEP 621. Version 1.8.4 is the latest supporting Python >=3.8,<4.0, under active development with regular releases.

pip install poetry-multiproject-plugin

Common errors

error AttributeError: 'NoneType' object has no attribute 'group' ↓

cause The plugin version <1.8.4 fails when importing a module without 'from' (e.g., 'import module') when using --with-top-namespace.

fix

Upgrade to poetry-multiproject-plugin>=1.8.4.

error ModuleNotFoundError for relative includes ↓

cause The relative package is not declared in pyproject.toml under 'packages'.

fix

Add the relative path to [tool.poetry.packages] or [project.urls]? Actually, ensure packages = [{ include = "../shared_lib", from = ".." }] in pyproject.toml.

error Poetry command not found: build-project ↓

cause The plugin is not installed or Poetry's plugin system is not detecting it.

fix

Install using 'poetry self add poetry-multiproject-plugin' and verify with 'poetry plugin show'.

Warnings

breaking Poetry v2 changes: The plugin v1.8.0+ adds support for Poetry v2, but older versions (pre-1.8.0) are incompatible with Poetry v2. Ensure you have at least v1.8.0 if using Poetry 2. ↓

fix Update plugin to >=1.8.0: poetry self add poetry-multiproject-plugin@latest

breaking PEP 621 support requires v1.8.1+: If your pyproject.toml uses [project] instead of [tool.poetry], you need plugin >=1.8.1. Older versions will fail to parse. ↓

fix Update to >=1.8.1: poetry self add poetry-multiproject-plugin@latest

gotcha Relative includes must be listed explicitly in pyproject.toml: The plugin only processes packages declared under [tool.poetry.packages] (or [project] in PEP 621). It does not automatically discover sibling packages. ↓

fix Explicitly declare each relative package include in your pyproject.toml under 'packages'.

gotcha Namespace packages: Use --with-top-namespace to handle top-level namespace imports. If you have a namespace package like 'namespace.submodule', you may need that flag to avoid import aliases with missing module names. ↓

fix Add the option to build command: poetry build-project --with-top-namespace

Install

poetry self add poetry-multiproject-plugin

Quickstart

Minimal setup to use the plugin; requires manual pyproject.toml configuration.

# Ensure the plugin is installed:
# poetry self add poetry-multiproject-plugin

# In your pyproject.toml, add:
# [tool.poetry.plugins.poetry]
# multiproject-plugin = "poetry_multiproject_plugin.plugin"

# Then use relative includes in pyproject.toml:
# [tool.poetry]
# packages = [
#     { include = "../shared_lib", from = ".." },
# ]

# Build the project with:
# poetry build-project

import subprocess
import os

# Example: run the build command (ensure plugin is configured)
subprocess.run(['poetry', 'build-project'], cwd=os.path.dirname(os.path.abspath(__file__)))