pypa/pip · error · InstallationError

Could not install requirement {req} because of HTTP error {e

Error message

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

What it means

Raised as InstallationError when downloading and unpacking a requirement fails with a NetworkConnectionError. At prepare.py:743-747, _prepare_linked_requirement wraps the unpack_url() call in try/except NetworkConnectionError and re-raises a user-facing InstallationError naming the requirement and the URL. This surfaces transport-layer failures with full requirement context.

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 d7d0d0a394)

Solutions

1. Inspect the embedded network error and the URL in the message to identify the failing host.
2. Increase resilience: pip install --retries 5 --timeout 60 -r requirements.txt.
3. Verify connectivity to the file host (curl -I <url>) and fix --index-url/--find-links if wrong.
4. Retry once transient issues clear; for persistent failures, switch to a reachable mirror or pre-download the artifact.

Example fix

# before
pip install -r requirements.txt  # -> Could not install req ... HTTP error ... for URL https://broken/files

# after (reachable mirror + retries)
pip install --retries 5 --timeout 60 \
  --index-url https://pypi.org/simple/ -r requirements.txt

import socket, urllib.parse
url = str(link)
host = urllib.parse.urlparse(url).hostname
if host:
    try:
        socket.getaddrinfo(host, 443)
    except socket.gaierror as e:
        raise SystemExit(f"index/file host {host} not resolvable: {e}")

from pip._internal.exceptions import InstallationError
for attempt in range(3):
    try:
        preparer.prepare_linked_requirement(req)
        break
    except InstallationError as e:
        if "HTTP error" not in str(e) or attempt == 2:
            raise
        logger.warning("transient HTTP failure (%s), retry %d", e, attempt + 1)

When it happens

Trigger: Any network failure while fetching a requirement's archive: DNS error, connection refused/reset, TLS failure, timeout, proxy error, or an HTTP 4xx/5xx from raise_for_status. The original NetworkConnectionError (and its message) is embedded in the InstallationError text.

Common situations: Intermittent network during dependency resolution, a private index going down mid-resolve, a flaky CDN, corporate firewall blocking the file host, or a mistyped --index-url/--find-links URL.

Related errors

• proxy-connection-failed
• No matching distribution found for {query}
• No module named {module!r}
• Can not combine '--user' and '--target'
• Target path exists but is not a directory, will not continue

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