pypa/pip · error · InstallationError

Cannot select requirements from pylock file

Error message

Cannot select requirements from pylock file {pylock_path_or_url!r}: {exc}

What it means

Raised as InstallationError by select_from_pylock_path_or_url (pylock.py:297) when the pylock file parses and validates successfully but lock.select() fails to produce requirements. The select() method iterates packages and picks the appropriate entry (wheel, sdist, archive, vcs, directory) for each; if a package has no installable entry, an invalid combination, or an internal error occurs during selection, it propagates here. This is the last-resort error in the pylock loading pipeline.

Solutions

Inspect the chained exception for the specific package and selection failure reason.
Ensure each package in the lock file has at least one valid installable entry (wheel, sdist, archive, vcs, or directory).
If platform-specific: verify the lock file contains an entry compatible with your current platform/Python version.
Regenerate the lock file ensuring all packages resolve to a concrete download artifact.

Example fix

// before (package with no installable artifact)
[[packages]]
name = "pkg"
version = "1.0"
# no wheel/sdist/archive/vcs/directory entry

// after
[[packages]]
name = "pkg"
version = "1.0"
[[packages.sdist]]
name = "pkg-1.0.tar.gz"
url = "https://..."
hashes = {sha256 = "..."}

Defensive patterns

Strategy: validation

Validate before calling

import tomllib
from pathlib import Path

def validate_pylock_packages_have_artifacts(path: str) -> list[str]:
    """Check each package in a pylock file has at least one installable entry."""
    data = tomllib.loads(Path(path).read_text(encoding='utf-8'))
    artifact_keys = {'vcs', 'directory', 'archive', 'sdist', 'wheels'}
    problems = []
    for pkg in data.get('packages', []):
        if not any(k in pkg and pkg[k] for k in artifact_keys):
            problems.append(f"Package {pkg.get('name','?')} has no installable artifact")
    return problems

Type guard

def package_has_installable_entry(pkg: dict) -> bool:
    """True if a pylock package dict has at least one artifact sub-table."""
    return any(k in pkg and pkg[k] for k in ('vcs', 'directory', 'archive', 'sdist', 'wheels'))

Try / catch

from pip._internal.exceptions import InstallationError

try:
    # pip install -r pylock.toml
    pass
except InstallationError as e:
    if 'Cannot select requirements from pylock file' in str(e):
        # selection failure: inspect each package for missing artifacts
        pass

Prevention

Ensure every package in a lock file has a concrete downloadable artifact (wheel/sdist/archive).
Validate lock files for platform compatibility before distributing.
Test lock file installation in CI on all target platforms before release.

When it happens

Trigger: A valid pylock file where lock.select() raises — e.g. a package entry with no wheel/sdist/archive/vcs/directory sub-table, or a combination of fields that the selection logic cannot handle. The except at line 296 catches it.

Common situations: A lock file where a package has an incomplete entry (e.g. name and version but no download artifact). A pylock file generated by a tool with a different selection model than pip expects. Platform-specific entries where no entry matches the current platform.

Related errors

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

Appendix: source

Thrown at src/pip/_internal/utils/pylock.py:297

        raise
    except Exception as exc:
        raise InstallationError(
            f"Error reading pylock file {pylock_path_or_url!r}: {exc}"
        ) from exc

    try:
        lock = Pylock.from_dict(tomllib.loads(pylock_content))
    except Exception as exc:
        raise InstallationError(
            f"Invalid pylock file {pylock_path_or_url!r}: {exc}"
        ) from exc

    try:
        # TODO: for completeness, pylock.select should support preferring sdist
        # over wheels to support --no-binary
        yield from lock.select()
    except Exception as exc:
        raise InstallationError(
            f"Cannot select requirements from pylock file {pylock_path_or_url!r}: {exc}"
        ) from exc

View on GitHub (pinned to f399c37189)