{"id":"0060d9fb2180ddf7","repo":"python-poetry/poetry","slug":"this-project-requires-poetry-version-constraint","errorCode":null,"errorMessage":"This project requires Poetry {version_constraint}, but you are using Poetry {version}","messagePattern":"This project requires Poetry (.+?), but you are using Poetry (.+?)","errorType":"exception","errorClass":"PoetryError","httpStatus":null,"severity":"error","filePath":"src/poetry/factory.py","lineNumber":61,"sourceCode":"\nlogger = logging.getLogger(__name__)\n\n\nclass Factory(BaseFactory):\n    \"\"\"\n    Factory class to create various elements needed by Poetry.\n    \"\"\"\n\n    def _ensure_valid_poetry_version(self, cwd: Path | None) -> None:\n        poetry_file = self.locate(cwd)\n        pyproject = PyProjectTOML(path=poetry_file)\n        poetry_config = pyproject.data.get(\"tool\", {}).get(\"poetry\", {})\n\n        if version_str := poetry_config.get(\"requires-poetry\"):\n            version_constraint = parse_constraint(version_str)\n            version = Version.parse(__version__)\n            if not version_constraint.allows(version):\n                raise PoetryError(\n                    f\"This project requires Poetry {version_constraint},\"\n                    f\" but you are using Poetry {version}\"\n                )\n\n    def create_poetry(\n        self,\n        cwd: Path | None = None,\n        with_groups: bool = True,\n        io: IO | None = None,\n        disable_plugins: bool = False,\n        disable_cache: bool = False,\n    ) -> Poetry:\n        if io is None:\n            io = NullIO()\n\n        self._ensure_valid_poetry_version(cwd)\n\n        base_poetry = super().create_poetry(cwd=cwd, with_groups=with_groups)","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/factory.py#L43-L79","documentation":"`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.","triggerScenarios":"Project pins `requires-poetry = \">=2.0\"` and you run Poetry 1.x; or pins `>=1.5,<2` and you run Poetry 2.0.","commonSituations":"Downgrading/upgrading Poetry; CI using a different Poetry than the project author; copying a `requires-poetry` from another project.","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."],"exampleFix":"# before\n# pyproject.toml: requires-poetry = \">=2.0\", running Poetry 1.8\n# after\npipx install poetry==2.0.0","handlingStrategy":"validation","validationCode":"from poetry.core.constraints.version import Version, parse_constraint\nfrom poetry import __version__\nconstraint = parse_constraint(\">=2.0\")\nif not constraint.allows(Version.parse(__version__)):\n    raise SystemExit(f\"requires Poetry {constraint}, running {__version__}\")","typeGuard":"def poetry_version_satisfies(requires_poetry: str, running: str) -> bool:\n    from poetry.core.constraints.version import Version, parse_constraint\n    return parse_constraint(requires_poetry).allows(Version.parse(running))","tryCatchPattern":null,"preventionTips":["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."],"tags":["versioning","compatibility","factory"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}