poetry: 'pyproject.toml changed significantly since poetry.lock was generated' in CI - how to fix

TL;DR

pyproject.toml changed without a lockfile refresh, so CI refuses to install. Run poetry lock locally, review the lockfile diff, commit it, and let CI run poetry install. Never regenerate the lockfile inside CI as a fix.

Error

poetry: 'pyproject.toml changed significantly since poetry.lock was generated' in CI  -  how to fix

Steps

1. Reproduce locally: poetry check --lock. Expected output: The same staleness error, confirming the lockfile is behind.

2. Refresh the lockfile: poetry lock. Expected output: poetry rewrites poetry.lock from the current pyproject.toml.

3. Review the diff: git diff poetry.lock, checking that version moves match the pyproject change. Expected output: The diff is scoped to the intended change.

4. Commit both files together. Expected output: The repo carries a consistent manifest and lockfile pair.

5. Confirm CI: the pipeline's poetry install step goes green. Expected output: CI installs deterministically from the committed lockfile.

When to use

• CI fails with pyproject.toml changed significantly since poetry.lock was generated
• Someone edited dependencies in pyproject.toml and forgot the lock step
• A merge changed pyproject.toml on both sides and the lockfile was not refreshed

When not to use

• poetry add fails with SolverProblemError; that is a constraint clash, not staleness
• The lockfile is current but install fails downloading; that is network
• You are tempted to run poetry lock in CI; commit the lockfile instead

Variant phrasings

poetry install fails in CI with a stale lockfile

The CI shape; the fix is a local poetry lock plus a commit, not a CI config change.

poetry check --lock fails after editing pyproject.toml

The local reproduction; check --lock is the fast gate before pushing.

Lockfile drift after merging dependency changes

Merge the manifests, run poetry lock once, commit the result.

Why it happens

Poetry records a content hash of pyproject.toml inside poetry.lock. Any dependency edit changes the hash, and poetry install in CI detects the mismatch and stops rather than install from a lockfile that no longer describes the manifest. The lock step re-hashes and re-resolves.

Edge cases

• poetry lock can move unrelated versions if constraints are loose; use poetry lock --no-update to keep existing versions where possible.
• If the pyproject edit itself was a mistake, revert it instead of re-locking around it.
• Agents that edit pyproject.toml need poetry lock in their routine; add poetry check --lock as a pre-push gate.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3tLUM7wP9tB0w15TcE0vHQ