python-poetry/poetry · error · RuntimeError

embedded {distribution} wheel not found

Error message

embedded {distribution} wheel not found

What it means

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.

Source

Thrown at src/poetry/utils/env/base_env.py:169

            if re.match(r"pip(?:\d+(?:\.\d+)?)?(?:\.exe)?$", p.name)
        )
        if pip_executables:
            pip_executable = pip_executables[0]
            if pip_executable.endswith(".exe"):
                pip_executable = pip_executable[:-4]

            self._pip_executable = pip_executable

    def find_executables(self) -> None:
        self._find_python_executable()
        self._find_pip_executable()

    def get_embedded_wheel(self, distribution: str) -> Path:
        wheel = get_embed_wheel(
            distribution, f"{self.version_info[0]}.{self.version_info[1]}"
        )
        if wheel is None:
            raise RuntimeError(f"embedded {distribution} wheel not found")
        return wheel.path

    @property
    def pip_embedded(self) -> Path:
        if self._embedded_pip_path is None:
            self._embedded_pip_path = self.get_embedded_wheel("pip") / "pip"
        return self._embedded_pip_path

    @property
    def pip(self) -> Path:
        """
        Path to current pip executable
        """
        # we do not use as_posix() here due to issues with windows pathlib2
        # implementation
        path = Path(self._bin(self._pip_executable))
        if not path.exists():
            return self.pip_embedded

View on GitHub (pinned to 92b74dcfe3)

Solutions

  1. Install pip into the environment manually: `python -m ensurepip --upgrade` or get-pip.py.
  2. Use a Python version supported by the installed virtualenv's seed wheels.
  3. Upgrade/reinstall virtualenv so its embedded wheels cover your interpreter.
  4. Provide a pip executable in the env's bin dir so the embedded-wheel fallback is not used.

Example fix

// before (no pip in env, embedded wheel missing)
# accessing env.pip raises RuntimeError
// after
python -m ensurepip --upgrade   # or: curl -sSL https://bootstrap.pypa.io/get-pip.py | python
# then env.pip resolves to the installed executable instead of the missing embedded wheel
Defensive patterns

Strategy: fallback

Validate before calling

import shutil, sys
from poetry.utils.env.base_env import EnvBase  # base class
# If no pip executable and embedded wheel may be missing, install pip first
if not shutil.which("pip") and shutil.which("python"):
    import subprocess
    subprocess.check_call([sys.executable, "-m", "ensurepip", "--upgrade"])

Try / catch

try:
    pip_path = env.pip
except RuntimeError as e:
    if "embedded" in str(e) and "wheel not found" in str(e):
        import subprocess, sys
        subprocess.check_call([sys.executable, "-m", "ensurepip", "--upgrade"])
        pip_path = env.pip  # now resolved via bin dir
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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