{"record":{"id":"53b35d0745415b8d","repo":"zed-industries/zed","slug":"debugpy-installation-failed-could-not-fetch-debug","errorCode":null,"errorMessage":"debugpy installation failed (could not fetch Debugpy's wheel)","messagePattern":"debugpy installation failed \\(could not fetch Debugpy's wheel\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/dap_adapters/src/python.rs","lineNumber":140,"sourceCode":"        let venv_python = self.base_venv_path(toolchain, delegate).await?;\n\n        let installation_succeeded = util::command::new_command(venv_python.as_ref())\n            .args([\n                \"-m\",\n                \"pip\",\n                \"download\",\n                \"debugpy\",\n                \"--only-binary=:all:\",\n                \"-d\",\n                download_dir.to_string_lossy().as_ref(),\n            ])\n            .output()\n            .await\n            .context(\"spawn system python\")?\n            .status\n            .success();\n        if !installation_succeeded {\n            bail!(\"debugpy installation failed (could not fetch Debugpy's wheel)\");\n        }\n\n        let wheel_path = std::fs::read_dir(&download_dir)?\n            .find_map(|entry| {\n                entry.ok().filter(|e| {\n                    e.file_type().is_ok_and(|typ| typ.is_file())\n                        && Path::new(&e.file_name()).extension() == Some(\"whl\".as_ref())\n                })\n            })\n            .with_context(|| format!(\"Did not find a .whl in {download_dir:?}\"))?;\n\n        util::archive::extract_zip(\n            &debug_adapters_dir().join(Self::ADAPTER_NAME),\n            File::open(&wheel_path.path()).await?,\n        )\n        .await?;\n\n        Ok(Arc::from(wheel_path.path()))","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/zed-industries/zed/blob/f4178619acd0d47ea1f76a2025c42962c6d6638c/crates/dap_adapters/src/python.rs#L122-L158","documentation":"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().","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (fails: pip download exits non-zero, pip output hidden)\n/Users/me/.venv/bin/python -m pip download debugpy --only-binary=:all: -d /tmp/wheelcheck\n# WARNING: pip is being invoked by an old interpreter or no matching distribution found\n\n# after\npython -m pip install --upgrade pip\nHTTPS_PROXY=http://proxy.corp:8080 /Users/me/.venv/bin/python -m pip download debugpy --only-binary=:all: -d /tmp/wheelcheck\n# Successfully downloaded debugpy-1.8.x wheel; retry the debug session in Zed","handlingStrategy":"retry","validationCode":"# pre-flight the exact bootstrap command before starting a debug session\npython -m pip --version || echo \"pip missing for this interpreter\"\npython -m pip download debugpy --only-binary=:all: -d \"$(mktemp -d)\" \\\n  && echo \"wheel fetch OK\" || echo \"fix network/proxy/pip first\"","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["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."],"tags":["python","debugpy","pip","network","dap","installation"],"backgroundTag":"pip-install-failed","analyzedSha":"f4178619acd0d47ea1f76a2025c42962c6d6638c","analyzedAt":"2026-08-20T19:29:52.058Z","contentChangedAt":"2026-08-20T19:29:52.058Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}