pypa/pip · error · ValueError

python_version must contain at least one item

Error message

python_version must contain at least one item

What it means

Raised as ValueError by pure_python_tags (tags.py:599-600) when python_version is an empty sequence (e.g. []). The function accepts None (defaults to sys.version_info[:2]) or a one/two-item version tuple, but an explicitly empty container is rejected because no interpreter tags can be generated from it.

Source

Thrown at src/pip/_vendor/packaging/tags.py:600

    python_version: PythonVersion | None = None,
) -> Iterator[Tag]:
    """
    Yields the pure-Python tags compatible with ``python_version``.

    The tags use the ``"none"`` ABI and ``"any"`` platform, so their
    generation does not depend on the running platform.

    .. versionadded:: 26.3

    :param Sequence python_version: A one- or two-item sequence representing the
                                 compatible version of Python. Defaults to
                                 ``sys.version_info[:2]``.
    :raises ValueError: If ``python_version`` is an empty sequence.
    """
    if python_version is None:
        python_version = sys.version_info[:2]
    elif not python_version:
        raise ValueError("python_version must contain at least one item")
    for version in _py_interpreter_range(python_version):
        yield Tag(version, "none", "any")


def compatible_tags(
    python_version: PythonVersion | None = None,
    interpreter: str | None = None,
    platforms: Iterable[str] | None = None,
) -> Iterator[Tag]:
    """
    Yields the tags for an interpreter compatible with the Python version
    specified by ``python_version``.

    The specific tags generated are:

    - ``py*-none-<platform>``
    - ``<interpreter>-none-any`` if ``interpreter`` is provided
    - ``py*-none-any``

View on GitHub (pinned to f399c37189)

Solutions

1. Guard against empty: if not python_version: python_version = sys.version_info[:2] (or skip the call).
2. Default the parameter to None and let pure_python_tags use sys.version_info.
3. Validate the list is non-empty at the source before passing.
4. Catch ValueError and fall back to the current interpreter version.

Example fix

# before
pure_python_tags([v for v in versions if v > 99])  # [] -> ValueError

# after - default to current interpreter when empty
pv = [v for v in versions if v > 99] or None
pure_python_tags(pv)  # None -> uses sys.version_info[:2]

import sys
def safe_python_version(v):
    return v or None  # let pure_python_tags use sys.version_info[:2]

def is_nonempty_version(v) -> bool:
    return v is None or (hasattr(v, '__len__') and len(v) >= 1)

try:
    list(pure_python_tags(pv))
except ValueError:
    list(pure_python_tags(None))

When it happens

Trigger: pure_python_tags([]); pure_python_tags(()) ; passing a list built from a filter that returned no elements (e.g. [v for v in versions if v > 99] yielding []).

Common situations: A version-detection helper that builds the python_version list dynamically and returns empty when no match is found; config that supplies an empty version range; conditional logic that clears the list before calling.

Related errors

• limit must be non-negative
• Tag {tag!r} has an empty component: {component!r}
• Tag component {component!r} is not in sorted order per PEP 4
• Compressed tag set would generate {tag_count} tags, exceedin
• Tag {tag!r} must have exactly three components

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