{"id":"b315c2007164666f","repo":"pypa/pip","slug":"invalid-pylock-file-pylock-path-or-url-r-exc","errorCode":null,"errorMessage":"Invalid pylock file {pylock_path_or_url!r}: {exc}","messagePattern":"Invalid pylock file (.+?): (.+?)","errorType":"exception","errorClass":"InstallationError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/pylock.py","lineNumber":288,"sourceCode":") -> Iterator[\n    tuple[\n        Package,\n        PackageVcs | PackageDirectory | PackageArchive | PackageWheel | PackageSdist,\n    ]\n]:\n    try:\n        pylock_content = _get_pylock_path_or_url_content(pylock_path_or_url, session)\n    except DiagnosticPipError:\n        raise\n    except Exception as exc:\n        raise InstallationError(\n            f\"Error reading pylock file {pylock_path_or_url!r}: {exc}\"\n        ) from exc\n\n    try:\n        lock = Pylock.from_dict(tomllib.loads(pylock_content))\n    except Exception as exc:\n        raise InstallationError(\n            f\"Invalid pylock file {pylock_path_or_url!r}: {exc}\"\n        ) from exc\n\n    try:\n        # TODO: for completeness, pylock.select should support preferring sdist\n        # over wheels to support --no-binary\n        yield from lock.select()\n    except Exception as exc:\n        raise InstallationError(\n            f\"Cannot select requirements from pylock file {pylock_path_or_url!r}: {exc}\"\n        ) from exc\n","sourceCodeStart":270,"sourceCodeEnd":300,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/utils/pylock.py#L270-L300","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\npip install lock.toml   # lock.toml was actually a hand-written requirements draft\n\n// after\n# regenerate the lock file with a compatible tool, then:\npip install lock.toml","handlingStrategy":"validation","validationCode":"import tomllib, pathlib\npath = pathlib.Path('pylock.toml')\ntry:\n    data = tomllib.loads(path.read_text(encoding='utf-8'))\nexcept tomllib.TOMLDecodeError as e:\n    raise SystemExit(f'pylock.toml is not valid TOML: {e}')\nif 'lock-version' not in data or 'packages' not in data:\n    raise SystemExit('pylock.toml missing required top-level keys')","typeGuard":"null","tryCatchPattern":"null","preventionTips":["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."],"tags":["pip","pylock","pep751","toml","configuration"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}