python-poetry/poetry · error · NoCompatiblePythonVersionFoundError

Poetry was unable to find a compatible version. If you have

Error message

Poetry was unable to find a compatible version. If you have one, you can explicitly use it via the "env use" command.

What it means

Raised as NoCompatiblePythonVersionFoundError (no 'given') in PythonManager.get_compatible_python when none of the discovered Python candidates (Python.find_all()) allows the project's python constraint. This is the auto-resolution fallback path: Poetry tried to find any interpreter that fits and failed.

Source

Thrown at src/poetry/utils/env/python/manager.py:323

        :param poetry: The poetry configuration containing package information,
                       including Python constraints.
        :param io: The input/output stream for error and status messages. Defaults
                   to a null I/O if not provided.
        :return: A Python instance representing a compatible Python version.
        :raises NoCompatiblePythonVersionFoundError: If no Python version matches
                the supported constraint.
        """
        io = io or NullIO()
        supported_python = poetry.package.python_constraint

        for python in cls.find_all():
            if python.version.allows_any(supported_python):
                io.write_error_line(
                    f"Using <c1>{python.name}</c1> ({python.patch_version})"
                )
                return python

        raise NoCompatiblePythonVersionFoundError(poetry.package.python_versions)

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Install a Python that satisfies the constraint: 'poetry python install <version>' or system/pyenv.
2. Loosen the python constraint in pyproject.toml to match an available interpreter.
3. Explicitly point to one you have: 'poetry env use <path-to-compliant-python>'.
4. Verify what Poetry can see: 'poetry python list' to enumerate discovered candidates.

Example fix

// before - only 3.9 available, project needs >=3.11
# poetry install -> falls through to get_compatible_python -> raise

// after
# poetry python install 3.12  (or loosen the constraint)
poetry install

from poetry.utils.env.python import Python

def any_compatible_python(poetry) -> bool:
    constraint = poetry.package.python_constraint
    return any(p.version.allows_any(constraint) for p in Python.find_all())

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 "unable to find a compatible version" in str(e)
    )

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

try:
    Python.get_compatible_python(poetry=poetry, io=io)
except NoCompatiblePythonVersionFoundError:
    # install one or widen the constraint
    run_cli(["poetry", "python", "install", earliest_allowed(poetry)])

When it happens

Trigger: Calling Python.get_compatible_python(poetry, io) - reached from create_venv when the preferred python is incompatible and no specific one was requested - and the loop at manager.py:316-321 finds zero matching candidates.

Common situations: Project requires python >=3.11 but only 3.9/3.10 are installed/on PATH; no system python at all; all discovered interpreters fail the constraint; a CI image provisioned with the wrong python versions.

Related errors

• Current Python version ({given}) is not allowed by the proje
• The specified Python version ({given}) is not supported by t
• This project requires Poetry {version_constraint}, but you a
• Missing [name] in source.
• The PyPI repository cannot be configured with a custom url.

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