pypa/pip · error · InvalidSdistFilename

Invalid sdist filename (extension must be '.tar.gz' or…

Error message

Invalid sdist filename (extension must be '.tar.gz' or '.zip'): {filename!r}

What it means

Raised by parse_sdist_filename() when the filename does not end with '.tar.gz' or '.zip' (utils.py:341-349). The source distribution format only permits these two extensions. The exception class is InvalidSdistFilename (a ValueError subclass).

Solutions

1. Ensure the filename ends with '.tar.gz' or '.zip'.
2. If the file is a wheel (.whl), use parse_wheel_filename() instead.
3. Re-package the sdist in a supported format if it uses .tar.bz2 or another archive type.

Example fix

// before
parse_sdist_filename('foo-1.0.tar.bz2')
// after
parse_sdist_filename('foo-1.0.tar.gz')

from packaging.utils import parse_sdist_filename, InvalidSdistFilename

def safe_parse_sdist(filename: str):
    if not (filename.endswith(".tar.gz") or filename.endswith(".zip")):
        raise ValueError(f"Not an sdist file: {filename!r}")
    return parse_sdist_filename(filename)

def is_sdist_filename(filename: str) -> bool:
    return isinstance(filename, str) and (
        filename.endswith(".tar.gz") or filename.endswith(".zip")
    )

from packaging.utils import InvalidSdistFilename

try:
    name, ver = parse_sdist_filename(filename)
except InvalidSdistFilename as e:
    logger.warning("Skipping non-sdist file %s: %s", filename, e)

When it happens

Trigger: Calling parse_sdist_filename() with a wheel filename, a '.tar.bz2' file, a '.7z' file, or any filename without a recognized sdist extension.

Common situations: Passing a wheel filename to the sdist parser, encountering a modern source archive format (.tar.bz2, .tar.zst) that the parser does not support, or a typo in the extension.

Related errors

• Invalid sdist filename (empty project name)
• Invalid sdist filename
• Invalid sdist filename (invalid version)
• Invalid sdist filename
• Cannot determine sdist filename

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

Appendix: source

Thrown at src/pip/_vendor/packaging/utils.py:346

    .. versionadded:: 20.9

    .. versionchanged:: 21.0
       Added support for ``.zip`` source distributions.

    .. versionchanged:: 23.2
       Raises :class:`InvalidSdistFilename` when the version component is invalid.

    .. versionchanged:: 26.3
       Raises :class:`InvalidSdistFilename` on an empty project name.

    .. _Source distribution format: https://packaging.python.org/specifications/source-distribution-format/#source-distribution-file-name
    """
    if filename.endswith(".tar.gz"):
        file_stem = filename[: -len(".tar.gz")]
    elif filename.endswith(".zip"):
        file_stem = filename[: -len(".zip")]
    else:
        raise InvalidSdistFilename(
            f"Invalid sdist filename (extension must be '.tar.gz' or '.zip'):"
            f" {filename!r}"
        )

    # We are requiring a PEP 440 version, which cannot contain dashes,
    # so we split on the last dash.
    name_part, sep, version_part = file_stem.rpartition("-")
    if not sep:
        raise InvalidSdistFilename(f"Invalid sdist filename: {filename!r}")
    if not name_part:
        raise InvalidSdistFilename(
            f"Invalid sdist filename (empty project name): {filename!r}"
        )

    name = canonicalize_name(name_part)

    try:
        version = Version(version_part)

View on GitHub (pinned to f399c37189)