{"id":"18719f3f30ec0156","repo":"python-poetry/poetry","slug":"could-not-find-the-python-executable-expected","errorCode":null,"errorMessage":"Could not find the python executable {expected}","messagePattern":"Could not find the python executable (.+?)","errorType":"exception","errorClass":"PythonVersionNotFoundError","httpStatus":null,"severity":"error","filePath":"src/poetry/utils/env/env_manager.py","lineNumber":120,"sourceCode":"        return venv\n\n    @cached_property\n    def envs_file(self) -> EnvsFile:\n        return EnvsFile(self._poetry.config.virtualenvs_path / self.ENVS_FILE)\n\n    @cached_property\n    def base_env_name(self) -> str:\n        return self.generate_env_name(\n            self._poetry.package.name,\n            str(self._poetry.file.path.parent),\n        )\n\n    def activate(self, python: str) -> Env:\n        venv_path = self._poetry.config.virtualenvs_path\n\n        python_instance = Python.get_by_name(python)\n        if python_instance is None:\n            raise PythonVersionNotFoundError(python)\n\n        create = False\n        # If we are required to create the virtual environment in the project directory,\n        # create or recreate it if needed\n        if self.use_in_project_venv():\n            create = False\n            venv = self.in_project_venv\n            if venv.is_dir():\n                # We need to check if the patch version is correct\n                _venv = VirtualEnv(venv)\n                current_patch = \".\".join(str(v) for v in _venv.version_info[:3])\n\n                if python_instance.patch_version.to_string() != current_patch:\n                    create = True\n\n            self.create_venv(python=python_instance, force=create)\n\n            return self.get(reload=True)","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/utils/env/env_manager.py#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nmanager.activate(\"python3.13\")  # not installed -> PythonVersionNotFoundError\n\n// after\nmanager.activate(\"/usr/bin/python3.11\")  # verified path","handlingStrategy":"validation","validationCode":"from poetry.utils.env.python import Python\n\ndef python_known(name: str) -> bool:\n    return Python.get_by_name(name) is not None\n\n# before activate:\nif not python_known(requested):\n    raise SystemExit(f\"interpreter {requested!r} not found; install it first\")","typeGuard":"from poetry.utils.env.python.exceptions import PythonVersionNotFoundError, PythonVersionError\n\ndef is_python_not_found(e: Exception) -> bool:\n    return isinstance(e, PythonVersionNotFoundError) or (\n        isinstance(e, PythonVersionError) and \"Could not find the python executable\" in str(e)\n    )","tryCatchPattern":"from poetry.utils.env.python.exceptions import PythonVersionNotFoundError\n\ntry:\n    manager.activate(requested)\nexcept PythonVersionNotFoundError:\n    # list what is actually available and prompt/choose\n    available = [p.name for p in Python.find_all()]\n    raise SystemExit(f\"{requested!r} not found. Available: {available}\")","preventionTips":["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'."],"tags":["python-version","env-use","interpreter","activation"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}