What causes "Invalid pylock file {pylock_path_or_url!r}: {exc}" in pypa/pip?

Validate the file is well-formed TOML first: `python -c "import tomllib; tomllib.load(open('pylock.toml','rb'))"`.

pypa/pip · error · InstallationError

Invalid pylock file {pylock_path_or_url!r}: {exc}

Error message

Invalid pylock file {pylock_path_or_url!r}: {exc}

What it means

Raised by pip when a pylock (PEP 751 lock file) passed via the lock-file requirement syntax cannot be parsed into a valid Pylock object. After pip reads the TOML content from disk or a URL, it calls Pylock.from_dict(tomllib.loads(content)); any exception during TOML parsing or schema validation is wrapped in InstallationError. The offending file path/URL and the underlying exception are both surfaced so you can tell whether it was malformed TOML or a schema mismatch.

Source

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

) -> Iterator[
    tuple[
        Package,
        PackageVcs | PackageDirectory | PackageArchive | PackageWheel | PackageSdist,
    ]
]:
    try:
        pylock_content = _get_pylock_path_or_url_content(pylock_path_or_url, session)
    except DiagnosticPipError:
        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 d7d0d0a394)

Solutions

Validate the file is well-formed TOML first: `python -c "import tomllib; tomllib.load(open('pylock.toml','rb'))"`.
Confirm the lock-version field matches a PEP 751 version your pip supports; regenerate the lock with the tool matching your pip version.
Diff the file against a known-good lock; look for truncated sections or stray merge-conflict markers.
If you meant to install the project, point pip at the package/pyproject.toml, not the lock file.

Example fix

// before
pip install lock.toml   # lock.toml was actually a hand-written requirements draft

// after
# regenerate the lock file with a compatible tool, then:
pip install lock.toml

Defensive patterns

Strategy: validation

Validate before calling

import tomllib, pathlib
path = pathlib.Path('pylock.toml')
try:
    data = tomllib.loads(path.read_text(encoding='utf-8'))
except tomllib.TOMLDecodeError as e:
    raise SystemExit(f'pylock.toml is not valid TOML: {e}')
if 'lock-version' not in data or 'packages' not in data:
    raise SystemExit('pylock.toml missing required top-level keys')

Type guard

null

Try / catch

null

Prevention

Validate pylock files with tomllib before invoking pip in CI.
Pin the lock-generating tool and pip to compatible versions.
Never hand-edit pylock files; regenerate them.
Store lock files under version control untouched by CRLF/BOM tooling.

When it happens

Trigger: Calling `pip install -r pylock.toml` / `pip install pylock.toml` / pip's requirement-from-lock-file API with a file that is not valid TOML or that does not match the PEP 751 lock-file schema (missing `lock-version`, missing `packages`, wrong types). Triggered inside select_from_pylock_path_or_url when tomllib.loads or Pylock.from_dict raises.

Common situations: Hand-edited pylock.toml with a typo or stray character; a lock file generated by an older/newer tool whose schema differs from what this pip understands; pointing pip at the project's pyproject.toml by mistake instead of the lock file; CRLF or BOM issues; truncation from a failed git checkout.

Related errors

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