python-poetry/poetry · error · NoCompatiblePythonVersionFoundError

The specified Python version ({given}) is not supported by t

Error message

The specified Python version ({given}) is not supported by the project ({expected}).

What it means

Raised as NoCompatiblePythonVersionFoundError (with a 'given' version) in EnvManager.create_venv when a specific Python was explicitly requested (the python argument is not None) but its patch version fails the project's python constraint. Unlike the auto-resolve path, Poetry stops immediately because the user explicitly chose this interpreter.

Source

Thrown at src/poetry/utils/env/env_manager.py:427

            )

        venv_path = (
            self.in_project_venv
            if in_project_venv
            else self._poetry.config.virtualenvs_path
        )
        if not name:
            name = self._poetry.package.name

        if not supported_python.allows(python.patch_version):
            # The currently activated or chosen Python version
            # is not compatible with the Python constraint specified
            # for the project.
            # If an executable has been specified, we stop there
            # and notify the user of the incompatibility.
            # Otherwise, we try to find a compatible Python version.
            if specific_python_requested:
                raise NoCompatiblePythonVersionFoundError(
                    self._poetry.package.python_versions,
                    python.patch_version.to_string(),
                )

            self._io.write_error_line(
                f"<warning>The currently activated Python version {python.patch_version.to_string()} is not"
                f" supported by the project ({self._poetry.package.python_versions}).\n"
                "Trying to find and use a compatible version.</warning> "
            )

            python = Python.get_compatible_python(poetry=self._poetry, io=self._io)

        if in_project_venv:
            venv = venv_path
        else:
            name = self.generate_env_name(name, str(cwd))
            name = f"{name}-py{python.minor_version.to_string()}"
            venv = venv_path / name

View on GitHub (pinned to 92b74dcfe3)

Solutions

Pick an interpreter version that satisfies the constraint in pyproject.toml.
Loosen the python constraint in [tool.poetry.dependencies] to include the requested version.
List available interpreters and choose: 'poetry env use' with a compliant one.
Confirm the requested version string is what you think (full patch vs minor).

Example fix

// before - project declares python = ">=3.10"
manager.activate("python3.8")  # -> NoCompatiblePythonVersionFoundError

// after - use a compliant interpreter or widen the constraint
manager.activate("python3.11")

Defensive patterns

Strategy: validation

Validate before calling

from poetry.utils.env.python import Python

def requested_python_allowed(poetry, python_name: str) -> bool:
    inst = Python.get_by_name(python_name)
    if inst is None:
        return False
    return poetry.package.python_constraint.allows(inst.patch_version)

Type guard

from poetry.utils.env.python.exceptions import NoCompatiblePythonVersionFoundError, PythonVersionError

def is_no_compatible_python(e: Exception) -> bool:
    return isinstance(e, NoCompatiblePythonVersionFoundError) or (
        isinstance(e, PythonVersionError) and "not supported by the project" in str(e)
    )

Try / catch

from poetry.utils.env.python.exceptions import NoCompatiblePythonVersionFoundError

try:
    manager.activate("python3.8")
except NoCompatiblePythonVersionFoundError:
    # either pick a compliant interpreter or widen the constraint
    raise SystemExit("choose a python allowed by [tool.poetry.dependencies] python")

Prevention

Check the python constraint in pyproject.toml before running 'poetry env use'.
Prefer letting Poetry auto-resolve (omit the explicit interpreter) when unsure.
Loosen the constraint if the requested version is genuinely acceptable.
Validate the interpreter's patch version against the constraint programmatically.

When it happens

Trigger: Calling create_venv(python=<Python instance>) (e.g. via 'poetry env use <python>') where python.patch_version is not allowed by the package's python_constraint. Exact branch: env_manager.py:419-430.

Common situations: 'poetry env use python3.8' on a project that declares python = ">=3.10"; pinning to an interpreter that the project's CI matrix doesn't support; mismatched python constraints after bumping the project's min version.

Related errors

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