python-poetry/poetry · error · RuntimeError

The lock file is not compatible with the current version of

Q: What causes "The lock file is not compatible with the current version of Poetry. Upgrade Poetry to be able to read the lock file or, alternatively, regenerate the lock file with the `poetry lock` command." in python-poetry/poetry?

Upgrade Poetry to a version whose read range covers the lockfile's lock-version (`poetry self update`).

Error message

The lock file is not compatible with the current version of Poetry.
Upgrade Poetry to be able to read the lock file or, alternatively, regenerate the lock file with the `poetry lock` command.

What it means

Raised by Locker._get_lock_data() when metadata['lock-version'] parses but falls outside the accepted read range (_READ_VERSION_RANGE = '>=1,<3'). The lockfile was written by a Poetry whose schema is too new (or too old) for this Poetry build to read safely. The fix is either to upgrade Poetry or to regenerate the lockfile with the installed version.

Source

Thrown at src/poetry/packages/locker.py:379

        metadata = lock_data["metadata"]
        if "lock-version" not in metadata:
            raise RuntimeError(
                "The lock file is not compatible with the current version of Poetry.\n"
                "Regenerate the lock file with the `poetry lock` command."
            )
        lock_version = Version.parse(metadata["lock-version"])
        current_version = Version.parse(self._VERSION)
        accepted_versions = parse_constraint(self._READ_VERSION_RANGE)
        lock_version_allowed = accepted_versions.allows(lock_version)
        if lock_version_allowed and current_version < lock_version:
            logger.warning(
                "The lock file might not be compatible with the current version of"
                " Poetry.\nUpgrade Poetry to ensure the lock file is read properly or,"
                " alternatively, regenerate the lock file with the `poetry lock`"
                " command."
            )
        elif not lock_version_allowed:
            raise RuntimeError(
                "The lock file is not compatible with the current version of Poetry.\n"
                "Upgrade Poetry to be able to read the lock file or, alternatively, "
                "regenerate the lock file with the `poetry lock` command."
            )

        return lock_data

    def _get_locked_package(
        self, info: dict[str, Any], with_dependencies: bool = True
    ) -> Package:
        source = info.get("source", {})
        source_type = source.get("type")
        url = source.get("url")
        if source_type in ["directory", "file"]:
            url = self.lock.parent.joinpath(url).resolve().as_posix()

        name = info["name"]
        package = Package(

View on GitHub (pinned to 92b74dcfe3)

Solutions

Upgrade Poetry to a version whose read range covers the lockfile's lock-version (`poetry self update`).
Alternatively regenerate the lockfile with your installed Poetry: `poetry lock`.
Align the whole team and CI on a single Poetry version to stop the schema churn.
Check `poetry --version` on every environment and pin it (e.g. via pipx, the official installer, or a pyproject build-requires).

Example fix

// before: lock-version 3.0 read by Poetry supporting <3
# [metadata]
# lock-version = "3.0"

// after (option A — upgrade reader)
$ poetry self update
// after (option B — regenerate with current Poetry)
$ poetry lock

Defensive patterns

Strategy: validation

Validate before calling

from poetry.core.constraints.version import Version, parse_constraint
import tomllib
from pathlib import Path

READ_RANGE = parse_constraint(">=1,<3")

def lockfile_version_compatible(path: Path) -> bool:
    with path.open("rb") as f:
        lv = tomllib.load(f).get("metadata", {}).get("lock-version")
    return bool(lv) and READ_RANGE.allows(Version.parse(lv))

Try / catch

from poetry.packages import Locker

try:
    locker._get_lock_data()
except RuntimeError as e:
    if "not compatible with the current version" in str(e):
        # either upgrade poetry or regenerate lock
        ...

Prevention

Standardise the whole team and CI on one Poetry version.
Re-run `poetry lock` after every Poetry upgrade.
Check `poetry --version` and the lock-version in a CI matrix step.
Communicate Poetry upgrades to all collaborators before they pull the new lockfile.

When it happens

Trigger: A teammate or CI image generated poetry.lock with Poetry 2.x producing lock-version 3.x (or vice-versa with a 0.x file), then you open the project with a Poetry whose _VERSION (2.1) and read range cannot accept it. Any locked read triggers it.

Common situations: Mixed Poetry versions across a team (some on 1.8, some on 2.x); CI pinned to an older Poetry while devs use newer; upgrading one machine but not others; lock-version bumped in a newer minor release.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/1781c3d5080440bb.json. Report an issue: GitHub.