pypa/pip · error · InstallationError

Could not install requirement

Error message

Could not install requirement {req} because of HTTP error {exc} for URL {link}

What it means

Raised in prepare_linked_requirement (prepare.py:743) when unpack_url raises NetworkConnectionError while downloading the requirement's archive/wheel. pip wraps it into an InstallationError naming the requirement, the HTTP error, and the URL so the user knows which package failed and where. It is a transient network-class failure, not a packaging problem.

Solutions

  1. Retry the install (transient network issues often resolve on retry).
  2. Check connectivity to the URL shown in the message (curl -I) and fix proxy/TLS/DNS settings.
  3. Configure pip's proxy and timeout: pip install --proxy http://... --timeout 60.
  4. Switch --index-url to a reachable mirror or pre-download the wheel to a local dir and install from there.

Example fix

# before
pip install pkg   # network error for URL https://...
# after
pip install --timeout 60 --retries 5 pkg
# or use a reachable mirror
pip install -i https://pypi.org/simple/ pkg
Defensive patterns

Strategy: retry

Validate before calling

import urllib.request, ssl

def url_reachable(url: str, timeout: float = 15.0) -> bool:
    try:
        req = urllib.request.Request(url, method='HEAD')
        urllib.request.urlopen(req, timeout=timeout)
        return True
    except Exception:
        return False

Type guard

def is_reachable(url: str) -> bool:
    return url_reachable(url)

Try / catch

import time
from subprocess import run, CalledProcessError

attempts = 3
for i in range(attempts):
    try:
        run(["pip", "install", "--timeout", "60", "--retries", "5", pkg], check=True)
        break
    except CalledProcessError:
        if i == attempts - 1:
            raise
        time.sleep(2 ** i)

Prevention

When it happens

Trigger: A GET to the requirement's link URL fails (DNS, TLS, timeout, proxy, 4xx/5xx, or connection reset) during the download/unpack step. Caught via 'except NetworkConnectionError as exc'.

Common situations: No/flaky internet, a corporate proxy or self-signed TLS interception, a private index that is down or misconfigured, rate-limiting (HTTP 429), or a temporarily unavailable CDN edge.

Related errors

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/f9c54b4389114ca4. Report an issue: GitHub.

Appendix: source

Thrown at src/pip/_internal/operations/prepare.py:744

                req.link = req.cached_wheel_source_link
                link = req.link

        self._ensure_link_req_src_dir(req, parallel_builds)

        if link.is_existing_dir():
            local_file = None
        elif link.url not in self._downloaded:
            try:
                local_file = unpack_url(
                    link,
                    req.source_dir,
                    self._download,
                    self.verbosity,
                    self.download_dir,
                    hashes,
                )
            except NetworkConnectionError as exc:
                raise InstallationError(
                    f"Could not install requirement {req} because of HTTP "
                    f"error {exc} for URL {link}"
                )
        else:
            file_path = self._downloaded[link.url]
            if hashes:
                hashes.check_against_path(file_path)
            local_file = File(file_path, content_type=None)

        # If download_info is set, we got it from the wheel cache.
        if req.download_info is None:
            # Editables don't go through this function (see
            # prepare_editable_requirement).
            assert not req.editable
            req.download_info = direct_url_from_link(link, req.source_dir)
            # Make sure we have a hash in download_info. If we got it as part of the
            # URL, it will have been verified and we can rely on it. Otherwise we
            # compute it from the downloaded file.

View on GitHub (pinned to f399c37189)