pypa/pip · error · InstallationError

Cannot determine archive format of

Error message

Cannot determine archive format of {location}

What it means

Raised by unpack_file() when pip cannot determine the archive format of a downloaded file. Format detection tries the HTTP content-type header, then the filename extension, then the file's magic signature (zip vs tar), and if all fail or are ambiguous, this error is raised. It indicates the downloaded artifact is not a recognizable zip or tar archive.

Solutions

1. Manually download the URL and inspect the file: 'file <downloaded>' and 'head -c 100 <downloaded> | xxd'
2. Verify the URL is correct and points to a .whl, .tar.gz, .zip, or .tar.bz2/xz artifact
3. Check for an HTML error page (404/403) returned instead of the archive
4. Clear pip's cache with 'pip cache purge' and retry to eliminate a corrupt cached download
5. If behind a proxy, verify it is not stripping or altering the content-type header

Example fix

// before
pip install https://example.com/mypackage
// after
# verify the URL resolves to a real archive
curl -sIL https://example.com/mypackage-1.0.tar.gz | grep -i content-type
# point at a concrete wheel or sdist filename
pip install https://example.com/mypackage-1.0-py3-none-any.whl

import zipfile, tarfile, os

def is_unpackable_archive(path: str) -> bool:
    if not os.path.isfile(path):
        return False
    if zipfile.is_zipfile(path):
        return True
    try:
        return tarfile.is_tarfile(path)
    except Exception:
        return False

# before unpacking
if not is_unpackable_archive(filename):
    raise ValueError(f'{filename} is not a recognized zip or tar archive')

import zipfile, tarfile

def is_valid_archive(path: str) -> bool:
    is_zip = zipfile.is_zipfile(path)
    is_tar = False
    try:
        is_tar = tarfile.is_tarfile(path)
    except Exception:
        pass
    return (is_zip and not is_tar) or (is_tar and not is_zip)

from pip._internal.exceptions import InstallationError

try:
    unpack_file(filename, location)
except InstallationError as e:
    if 'Cannot determine archive format' in str(e):
        # re-download or fix the URL
        os.remove(filename)
        raise DownloadError(f'downloaded file is not a valid archive: {e}')
    raise

When it happens

Trigger: Calling unpack_file() with a file whose content-type is not application/zip or application/x-gzip, whose extension is not a known archive extension, and whose magic bytes are neither unambiguously zip nor tar — or where both magic checks return true (ambiguous).

Common situations: A download URL returned an HTML error page (e.g. 404 page) instead of the archive. A corrupted or truncated download. A package URL pointing to a raw .py file or a directory. A proxy or CDN mangling the content-type. An archive in an unsupported format (e.g. .rar, .7z).

Related errors

• Cannot set --home and --prefix together
• Cannot set --user and --prefix together
• Could not install locked package
• Could not install requirement
• could not read file

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

Appendix: 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 f399c37189)