What causes "Could not find the python executable {expected}" in python-poetry/poetry?

List what Poetry can see: 'poetry env list' and check installed interpreters with 'python --version', 'python3.x --version'.

python-poetry/poetry · error · PythonVersionNotFoundError

Could not find the python executable {expected}

Error message

Could not find the python executable {expected}

What it means

Raised as PythonVersionNotFoundError in EnvManager.activate when Python.get_by_name(python) returns None - i.e. the python identifier passed to 'poetry env use' / activate cannot be resolved to any known Python interpreter (by name, version string, or path). It tells the user the executable they asked Poetry to switch to does not exist.

Source

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

        return venv

    @cached_property
    def envs_file(self) -> EnvsFile:
        return EnvsFile(self._poetry.config.virtualenvs_path / self.ENVS_FILE)

    @cached_property
    def base_env_name(self) -> str:
        return self.generate_env_name(
            self._poetry.package.name,
            str(self._poetry.file.path.parent),
        )

    def activate(self, python: str) -> Env:
        venv_path = self._poetry.config.virtualenvs_path

        python_instance = Python.get_by_name(python)
        if python_instance is None:
            raise PythonVersionNotFoundError(python)

        create = False
        # If we are required to create the virtual environment in the project directory,
        # create or recreate it if needed
        if self.use_in_project_venv():
            create = False
            venv = self.in_project_venv
            if venv.is_dir():
                # We need to check if the patch version is correct
                _venv = VirtualEnv(venv)
                current_patch = ".".join(str(v) for v in _venv.version_info[:3])

                if python_instance.patch_version.to_string() != current_patch:
                    create = True

            self.create_venv(python=python_instance, force=create)

            return self.get(reload=True)

View on GitHub (pinned to 92b74dcfe3)

Solutions

List what Poetry can see: 'poetry env list' and check installed interpreters with 'python --version', 'python3.x --version'.
Install the requested interpreter (system package, pyenv install, or 'poetry python install <version>').
Pass a fully-qualified absolute path to an interpreter you have verified exists.
Correct the typo / use a version string that matches an installed interpreter.

Example fix

// before
manager.activate("python3.13")  # not installed -> PythonVersionNotFoundError

// after
manager.activate("/usr/bin/python3.11")  # verified path

Defensive patterns

Strategy: validation

Validate before calling

from poetry.utils.env.python import Python

def python_known(name: str) -> bool:
    return Python.get_by_name(name) is not None

# before activate:
if not python_known(requested):
    raise SystemExit(f"interpreter {requested!r} not found; install it first")

Type guard

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

def is_python_not_found(e: Exception) -> bool:
    return isinstance(e, PythonVersionNotFoundError) or (
        isinstance(e, PythonVersionError) and "Could not find the python executable" in str(e)
    )

Try / catch

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

try:
    manager.activate(requested)
except PythonVersionNotFoundError:
    # list what is actually available and prompt/choose
    available = [p.name for p in Python.find_all()]
    raise SystemExit(f"{requested!r} not found. Available: {available}")

Prevention

Validate the interpreter against Python.get_by_name before calling activate.
Prefer absolute paths to verified interpreters over guessed version strings.
In CI, install the required python in the image setup step and verify with 'python -V'.
Use 'poetry env list' / 'poetry python list' to confirm available interpreters before 'env use'.

When it happens

Trigger: Calling EnvManager.activate(python) (or the 'poetry env use <python>' CLI) with a value like 'python3.99', a typo'd name ('pyhton'), a version not installed, or a path to an interpreter that does not exist. Triggered exactly at env_manager.py:118-120 when get_by_name yields None.

Common situations: User specifies a Python they haven't installed; switching to a version that was removed from the system; a CI image that lacks the requested python3.x; copy-paste typos in the version; expecting pyenv-managed python to be visible but it isn't on PATH.

Related errors

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