debugpy installation failed (could not fetch Debugpy's wheel

Error message

debugpy installation failed (could not fetch Debugpy's wheel)

What it means

Thrown while bootstrapping the Python debug adapter: fetch_wheel() runs `<venv python> -m pip download debugpy --only-binary=:all: -d <debug_adapters>/python/wheels` and this error means that pip invocation exited with a non-zero status, so no debugpy wheel was obtained for the session. It fires before any debug session starts, and the error text deliberately names the wheel-fetch step because the underlying pip output is swallowed by .output().

Source

Thrown at crates/dap_adapters/src/python.rs:140

        let venv_python = self.base_venv_path(toolchain, delegate).await?;

        let installation_succeeded = util::command::new_command(venv_python.as_ref())
            .args([
                "-m",
                "pip",
                "download",
                "debugpy",
                "--only-binary=:all:",
                "-d",
                download_dir.to_string_lossy().as_ref(),
            ])
            .output()
            .await
            .context("spawn system python")?
            .status
            .success();
        if !installation_succeeded {
            bail!("debugpy installation failed (could not fetch Debugpy's wheel)");
        }

        let wheel_path = std::fs::read_dir(&download_dir)?
            .find_map(|entry| {
                entry.ok().filter(|e| {
                    e.file_type().is_ok_and(|typ| typ.is_file())
                        && Path::new(&e.file_name()).extension() == Some("whl".as_ref())
                })
            })
            .with_context(|| format!("Did not find a .whl in {download_dir:?}"))?;

        util::archive::extract_zip(
            &debug_adapters_dir().join(Self::ADAPTER_NAME),
            File::open(&wheel_path.path()).await?,
        )
        .await?;

        Ok(Arc::from(wheel_path.path()))

View on GitHub (pinned to f4178619ac)

Solutions

Run the exact command manually with the same interpreter to see the real pip error: `<python> -m pip download debugpy --only-binary=:all: -d /tmp/wheelcheck`.
Fix whatever pip reports: set HTTPS_PROXY/HTTP_PROXY or install the corporate CA cert if TLS to pypi.org fails.
Ensure pip exists and is current for that interpreter: `<python> -m ensurepip` then `<python> -m pip install --upgrade pip`.
Delete Zed's cached wheels dir (<data dir>/debug_adapters/python/wheels) so a poisoned earlier download is retried.
On platforms without a debugpy wheel, install debugpy into the environment (`pip install debugpy`) and debug via `program: python ... args: [-m, debugpy, --listen, ...]` so no wheel download is needed.

Example fix

# before (fails: pip download exits non-zero, pip output hidden)
/Users/me/.venv/bin/python -m pip download debugpy --only-binary=:all: -d /tmp/wheelcheck
# WARNING: pip is being invoked by an old interpreter or no matching distribution found

# after
python -m pip install --upgrade pip
HTTPS_PROXY=http://proxy.corp:8080 /Users/me/.venv/bin/python -m pip download debugpy --only-binary=:all: -d /tmp/wheelcheck
# Successfully downloaded debugpy-1.8.x wheel; retry the debug session in Zed

Defensive patterns

Strategy: retry

Validate before calling

# pre-flight the exact bootstrap command before starting a debug session
python -m pip --version || echo "pip missing for this interpreter"
python -m pip download debugpy --only-binary=:all: -d "$(mktemp -d)" \
  && echo "wheel fetch OK" || echo "fix network/proxy/pip first"

Try / catch

Match on the bootstrap error and distinguish spawn failure ("spawn system python" context — interpreter problem) from the download-failure message (network/pip problem) so the user is told which of the two to fix; retry only the network variant with a backoff.

Prevention

Keep a known-good interpreter with pip as the detected Python for the project.
Pre-install debugpy into the environment or pre-warm the wheels dir on machines with restricted networks.
Configure HTTPS_PROXY and corporate CA certs in the environment Zed inherits.

When it happens

Trigger: Starting a Python debug/attach session when: the resolved Python interpreter is missing or a stub (e.g. Windows Store python), pip is not installed for that interpreter, pip is too old to understand `--only-binary=:all:`, the machine cannot reach pypi.org (offline, firewall, corporate proxy, MITM TLS interception), or no prebuilt debugpy wheel exists for the platform.

Common situations: Corporate proxies or Zscaler-style TLS interception rejecting pypi.org; pyenv/virtualenv environments without pip; air-gapped CI machines; a stale or corrupted wheels directory under Zed's debug_adapters dir; default interpreter pointing at a broken Homebrew/ASDF python after an OS upgrade.

Related errors

AI-assisted analysis of zed-industries/zed@f4178619ac (2026-08-20). Data as JSON: /api/errors/53b35d0745415b8d. Report an issue: GitHub.