pypa/pip · error · InstallationError

Error reading pylock file {pylock_path_or_url!r}: {exc}

Error message

Error reading pylock file {pylock_path_or_url!r}: {exc}

What it means

InstallationError wrapping any non-diagnostic exception raised while fetching/reading the pylock file content in _get_pylock_path_or_url_content (or, by chaining, an earlier read failure). DiagnosticPipError subclasses are re-raised unchanged; everything else (network, filesystem, decode) is wrapped with the lock path for context.

Source

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

    # Assume this is a bare path.
    return Path(path_or_url).read_text(encoding="utf-8")


def select_from_pylock_path_or_url(
    pylock_path_or_url: str,
    session: PipSession,
) -> 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

Verify the pylock path/URL resolves (curl/wget the URL, or ls the local path).
For HTTP errors, check status with `curl -i <url>` and fix auth/proxy/cert as needed.
For local files, confirm the path and read permissions; convert the file to UTF-8 if decoding failed.
If it's a transient network issue, retry; ensure PIP_INDEX_URL/PIP_CERT/PIP_CLIENT_CERT are set for private hosts.

Example fix

# before
pip install -r https://example.com/typo-lock.toml   # 404 → Error reading pylock file

# after - correct URL, verify first
curl -i https://example.com/lock.toml
pip install -r https://example.com/lock.toml

Defensive patterns

Strategy: try-catch

Validate before calling

def pylock_url_is_fetchable(url, session):
    try:
        resp = session.get(url, stream=True)
        resp.raise_for_status()
        return True
    except Exception as e:
        return False
# probe before invoking pip -r <remote lock>

Try / catch

try:
    pip_install('-r', lock_path_or_url)
except InstallationError as e:
    msg = str(e)
    if 'Error reading pylock file' in msg:
        if is_transient_network(msg):    # 5xx / connection / DNS
            backoff_and_retry(lambda: pip_install('-r', lock_path_or_url))
        else:
            fix_lock_source(lock_path_or_url)  # 404 / perms / encoding
            pip_install('-r', lock_path_or_url)
    else:
        raise

Prevention

curl/verify the lock URL/path before pip uses it.
Ensure UTF-8 encoding for locally-served pylock files.
Configure PIP_CERT/PIP_CLIENT_CERT/proxy for private hosts hosting the lock.

When it happens

Trigger: select_from_pylock_path_or_url calls _get_pylock_path_or_url_content; it raises a non-DiagnosticPipError (HTTP error from session.get, connection refused, DNS failure, file not found, permission denied, unicode decode error on a local file). The except Exception catches and re-raises as InstallationError 'Error reading pylock file ...: <exc>'.

Common situations: Typo in the pylock URL; the host is down or returns 404/500; the local pylock path doesn't exist or isn't readable; the file isn't UTF-8; corporate proxy/firewall blocking the fetch; expired/misconfigured credentials for a private index hosting the lock.

Related errors

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