python-poetry/poetry · error · PoetryError

This project requires Poetry {version_constraint}, but you a

Error message

This project requires Poetry {version_constraint}, but you are using Poetry {version}

What it means

`PoetryError` from `_ensure_valid_poetry_version` (factory.py:52-64) when the project declares `requires-poetry = "<constraint>"` under `[tool.poetry]` and the running Poetry version is not allowed by that constraint. Poetry refuses to operate to guarantee compatibility with the project's expected feature set.

Source

Thrown at src/poetry/factory.py:61

logger = logging.getLogger(__name__)


class Factory(BaseFactory):
    """
    Factory class to create various elements needed by Poetry.
    """

    def _ensure_valid_poetry_version(self, cwd: Path | None) -> None:
        poetry_file = self.locate(cwd)
        pyproject = PyProjectTOML(path=poetry_file)
        poetry_config = pyproject.data.get("tool", {}).get("poetry", {})

        if version_str := poetry_config.get("requires-poetry"):
            version_constraint = parse_constraint(version_str)
            version = Version.parse(__version__)
            if not version_constraint.allows(version):
                raise PoetryError(
                    f"This project requires Poetry {version_constraint},"
                    f" but you are using Poetry {version}"
                )

    def create_poetry(
        self,
        cwd: Path | None = None,
        with_groups: bool = True,
        io: IO | None = None,
        disable_plugins: bool = False,
        disable_cache: bool = False,
    ) -> Poetry:
        if io is None:
            io = NullIO()

        self._ensure_valid_poetry_version(cwd)

        base_poetry = super().create_poetry(cwd=cwd, with_groups=with_groups)

View on GitHub (pinned to 92b74dcfe3)

Solutions

Upgrade/downgrade Poetry to satisfy the constraint: `pipx install poetry==<version>` or `poetry self update`.
If the constraint is too strict, widen it in pyproject.toml after verifying compatibility.
Use `poetry env use` and a managed environment to control the Poetry version if needed.

Example fix

# before
# pyproject.toml: requires-poetry = ">=2.0", running Poetry 1.8
# after
pipx install poetry==2.0.0

Defensive patterns

Strategy: validation

Validate before calling

from poetry.core.constraints.version import Version, parse_constraint
from poetry import __version__
constraint = parse_constraint(">=2.0")
if not constraint.allows(Version.parse(__version__)):
    raise SystemExit(f"requires Poetry {constraint}, running {__version__}")

Type guard

def poetry_version_satisfies(requires_poetry: str, running: str) -> bool:
    from poetry.core.constraints.version import Version, parse_constraint
    return parse_constraint(requires_poetry).allows(Version.parse(running))

Prevention

Pin Poetry in CI to match `requires-poetry`.
Keep the constraint permissive (`>=X` rather than tight ranges) unless you need strict control.
Document the required Poetry version in the README.

When it happens

Trigger: Project pins `requires-poetry = ">=2.0"` and you run Poetry 1.x; or pins `>=1.5,<2` and you run Poetry 2.0.

Common situations: Downgrading/upgrading Poetry; CI using a different Poetry than the project author; copying a `requires-poetry` from another project.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/0060d9fb2180ddf7.json. Report an issue: GitHub.