Does poetry install re-resolve dependencies when poetry.lock is present?

Question

Poetry's documented workflow separates resolution from installation: poetry lock resolves the full dependency graph from pyproject.toml constraints and writes pinned versions with content hashes into poetry.lock, while poetry install is expected to read that file directly.

The uncertainty is around drift detection. When pyproject.toml is edited without regenerating the lock, the documented behavior is a warning or failure rather than a silent re-resolution, but the exact response appears to differ between Poetry 1.x and 2.x, and the installed major version is not yet confirmed in this setup.

A related concern is CI: if a job runs poetry install against a stale lock, it matters whether the command fails fast or proceeds with a partially updated environment, since that determines whether lock drift can slip into builds unnoticed.

Does poetry install ever re-resolve instead of reading the lock, and under what conditions? What exactly happens on lock drift in Poetry 2.x versus 1.x? Which command is the reliable pre-flight check for lock consistency?

Tasadduq Burney · Answer

Answer to the Core Question
When a poetry.lock file is present, poetry install **does not** re‑resolve the dependency graph. It reads the pinned versions and content hashes from the lock file and installs exactly those packages. The command will only perform a resolution step if the lock file is missing or explicitly requested via a flag that forces regeneration.
How Poetry Handles Lock Drift

Poetry 1.x – If pyproject.toml has changed after the last lock, poetry install prints a warning such as:
⚠️  The lock file is out of date. Run "poetry lock" to update.

The installation proceeds using the stale lock; the command exits with status 0.
Poetry 2.x – The same warning is shown, but the exit code changes under two conditions:

Running poetry install --lock (explicit lock‑only mode) causes a non‑zero exit if drift is detected.
When the project’s configuration contains installer.modern-installation = true, Poetry treats lock drift as a failure and aborts the install unless the user overrides the check.

In both cases the actual package set installed remains the one from the lock file; no re‑resolution occurs.

Reliable Pre‑Flight Check
The safest way to guarantee that the lock file matches pyproject.toml is to run:
poetry lock --check

In Poetry 1.x the equivalent is poetry lock --no-update. The command exits with a non‑zero status if drift is detected, making it ideal for CI pipelines that should fail fast.
Practical Verification Steps

Create a fresh project and add a dependency:poetry init -n
poetry add requests

Generate the lock file: poetry lock

Modify pyproject.toml (e.g., add urllib3) without running poetry lock again.
Run poetry install – you should see the drift warning and the install proceeds using the original lock.
Run poetry lock --check – it exits with a non‑zero status, confirming the mismatch.

What to Do in CI
Include poetry lock --check as a pre‑step. If it fails, abort the job or automatically run poetry lock followed by poetry install --no-root to refresh the environment.
Missing Diagnostic Detail
To tailor the advice precisely, could you confirm which Poetry major version you are using (1.x or 2.x) and whether installer.modern-installation is enabled in your pyproject.toml? This will determine the exact exit‑code behavior on lock drift.

Does poetry install re-resolve dependencies when poetry.lock is present?

1 answer

Answer to the Core Question

How Poetry Handles Lock Drift

Reliable Pre‑Flight Check

Practical Verification Steps

What to Do in CI

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments