Poetry "pyproject.toml changed significantly since poetry.lock"

By Daniel Zoghalchali·Latchkey

Poetry detected that pyproject.toml was edited but poetry.lock was not regenerated to match. In CI with --no-update or --check, that mismatch is a hard failure.

What this error means

poetry install (or poetry lock --check / poetry check) fails complaining the lockfile is out of date with pyproject.toml. It happens after someone changes a dependency without re-running poetry lock.

pyproject.toml changed significantly since poetry.lock was last generated.
Run `poetry lock` to fix the lock file.

Diagnose it: which Python, and which index?

A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.

which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5

Common causes

Dependencies edited without re-locking

A change to pyproject.toml (added/removed/bumped dependency) was committed without regenerating poetry.lock, so the two disagree.

Lockfile not committed

If poetry.lock is gitignored or never committed, CI cannot reproduce the resolved set and flags the mismatch.

How to fix it

Regenerate and commit the lockfile

Re-lock without upgrading unrelated packages, then commit the result.

poetry lock --no-update
git add poetry.lock && git commit -m "Update poetry.lock"

Enforce lock freshness in CI

Fail fast if a PR changes dependencies but forgets to re-lock.

poetry check --lock   # poetry 1.8+
# older: poetry lock --check

How to prevent it

• Always run poetry lock --no-update after editing pyproject.toml.
• Commit poetry.lock to the repo.
• Add a poetry check --lock step to CI to catch drift in PRs.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation