{"id":"45553ffe3c9ac79b","repo":"python-poetry/poetry","slug":"embedded-distribution-wheel-not-found","errorCode":null,"errorMessage":"embedded {distribution} wheel not found","messagePattern":"embedded (.+?) wheel not found","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/poetry/utils/env/base_env.py","lineNumber":169,"sourceCode":"            if re.match(r\"pip(?:\\d+(?:\\.\\d+)?)?(?:\\.exe)?$\", p.name)\n        )\n        if pip_executables:\n            pip_executable = pip_executables[0]\n            if pip_executable.endswith(\".exe\"):\n                pip_executable = pip_executable[:-4]\n\n            self._pip_executable = pip_executable\n\n    def find_executables(self) -> None:\n        self._find_python_executable()\n        self._find_pip_executable()\n\n    def get_embedded_wheel(self, distribution: str) -> Path:\n        wheel = get_embed_wheel(\n            distribution, f\"{self.version_info[0]}.{self.version_info[1]}\"\n        )\n        if wheel is None:\n            raise RuntimeError(f\"embedded {distribution} wheel not found\")\n        return wheel.path\n\n    @property\n    def pip_embedded(self) -> Path:\n        if self._embedded_pip_path is None:\n            self._embedded_pip_path = self.get_embedded_wheel(\"pip\") / \"pip\"\n        return self._embedded_pip_path\n\n    @property\n    def pip(self) -> Path:\n        \"\"\"\n        Path to current pip executable\n        \"\"\"\n        # we do not use as_posix() here due to issues with windows pathlib2\n        # implementation\n        path = Path(self._bin(self._pip_executable))\n        if not path.exists():\n            return self.pip_embedded","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/utils/env/base_env.py#L151-L187","documentation":"EnvManager/base_env.get_embedded_wheel raises RuntimeError when virtualenv's get_embed_wheel returns no bundled wheel for the requested distribution and Python version (base_env.py:164-170). It is hit when Poetry falls back to an embedded wheel (e.g. pip) because no pip executable was found in the env's bin dir, and virtualenv has no seed wheel for that interpreter.","triggerScenarios":"Accessing env.pip (base_env.py:179-188) on an environment where the pip executable is absent AND get_embed_wheel('pip', '<major>.<minor>') returns None — typically an unusual/very new or very old Python version not bundled by the installed virtualenv.","commonSituations":"A Python version newer than the virtualenv release's bundled wheels; a stripped/custom Python build with no pip; a corrupted virtualenv install whose seed wheels are missing.","solutions":["Install pip into the environment manually: `python -m ensurepip --upgrade` or get-pip.py.","Use a Python version supported by the installed virtualenv's seed wheels.","Upgrade/reinstall virtualenv so its embedded wheels cover your interpreter.","Provide a pip executable in the env's bin dir so the embedded-wheel fallback is not used."],"exampleFix":"// before (no pip in env, embedded wheel missing)\n# accessing env.pip raises RuntimeError\n// after\npython -m ensurepip --upgrade   # or: curl -sSL https://bootstrap.pypa.io/get-pip.py | python\n# then env.pip resolves to the installed executable instead of the missing embedded wheel","handlingStrategy":"fallback","validationCode":"import shutil, sys\nfrom poetry.utils.env.base_env import EnvBase  # base class\n# If no pip executable and embedded wheel may be missing, install pip first\nif not shutil.which(\"pip\") and shutil.which(\"python\"):\n    import subprocess\n    subprocess.check_call([sys.executable, \"-m\", \"ensurepip\", \"--upgrade\"])","typeGuard":null,"tryCatchPattern":"try:\n    pip_path = env.pip\nexcept RuntimeError as e:\n    if \"embedded\" in str(e) and \"wheel not found\" in str(e):\n        import subprocess, sys\n        subprocess.check_call([sys.executable, \"-m\", \"ensurepip\", \"--upgrade\"])\n        pip_path = env.pip  # now resolved via bin dir\n    else:\n        raise","preventionTips":["Ensure pip is installed in the target environment (ensurepip / get-pip).","Use Python versions covered by the installed virtualenv's seed wheels.","Upgrade virtualenv when adopting a new Python release."],"tags":["environment","virtualenv","pip","embedded-wheel"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}