What causes "Cannot determine archive format of {location}" in pypa/pip?

Inspect the file: `file path` and `head -c 512 path | xxd` to see what was actually downloaded.

pypa/pip · error · InstallationError

Cannot determine archive format of {location}

Error message

Cannot determine archive format of {location}

What it means

InstallationError raised by unpack_file when pip cannot determine whether an archive is a zip or tar. After checking content-type and file extension, pip probes with zipfile.is_zipfile and tarfile.is_tarfile; if both return False (or both True, the ambiguous case logged at critical), it gives up. This indicates a file that is neither a supported archive nor recognized by signature.

Source

Thrown at src/pip/_internal/utils/unpacking.py:407

    # avoid ambiguous case where both signature checks return True
    is_zipfile = zipfile.is_zipfile(filename)
    is_tarfile = tarfile.is_tarfile(filename)
    if is_zipfile and not is_tarfile:
        return _unzip()
    if is_tarfile and not is_zipfile:
        return _untar()
    if is_zipfile and is_tarfile:
        logger.error("Ambiguous file signature in %s.", filename)

    logger.critical(
        "Cannot unpack file %s (downloaded from %s, content-type: %s); "
        "cannot detect archive format",
        filename,
        location,
        content_type,
    )
    raise InstallationError(f"Cannot determine archive format of {location}")

View on GitHub (pinned to d7d0d0a394)

Solutions

Inspect the file: `file path` and `head -c 512 path | xxd` to see what was actually downloaded.
Re-download with `-v` to see the resolved URL and HTTP status; verify content-type.
Confirm the file is a real archive: try `unzip -t` or `tar -tvf` manually.
If using a private index, check its auth/URL configuration so it serves the artifact instead of a redirect/HTML page.

Example fix

// before
# index served an HTML 404 page; pip cached it as the wheel
pip install pkg-1.0-py3-none-any.whl

// after
# fix the index URL / auth, clear the cache, retry:
pip cache purge && pip install -i https://pypi.org/simple/ pkg==1.0

Defensive patterns

Strategy: validation

Validate before calling

import zipfile, tarfile, os
EXTS = ('.zip','.whl','.egg','.tar','.tar.gz','.tgz','.tar.bz2','.tbz2','.tar.xz','.txz')
def looks_like_archive(path: str) -> bool:
    if path.lower().endswith(EXTS):
        return True
    return zipfile.is_zipfile(path) or tarfile.is_tarfile(path)

Type guard

null

Try / catch

null

Prevention

Verify the download URL resolves to a real artifact (check status code + content-type).
Use trusted indexes over HTTPS.
Inspect suspicious files with `file path` before install.
Configure private index auth correctly so it doesn't serve HTML.

When it happens

Trigger: Calling unpack_file on a downloaded/cached file whose extension is unknown, content-type is unhelpful, and whose magic bytes are neither zip nor tar. Common with renamed files, HTML error pages saved with archive extensions, or zero-byte downloads.

Common situations: Index returned an HTML 404/login page saved as the .whl; a gzip-compressed single file (not a tar); an unsupported compression like zstd alone; truncated download; the URL redirected through a CDN that served a placeholder.

Related errors

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