poetry lock: update poetry.lock without upgrading dependencies
- tool
- Poetry
- versions
- Poetry 2.x, Poetry 1.x
- os
- any
poetry lock resolves the dependencies in pyproject.toml and writes the exact versions to poetry.lock. In Poetry 2 it keeps the versions that are already locked whenever they still satisfy the constraints, so it only changes what your edit requires; use poetry lock --regenerate (or poetry update) to move everything to the newest allowed versions. In Poetry 1.x the same "keep" behaviour needed poetry lock --no-update.
Detect a stale lock file and fix it
cat > pyproject.toml <<'EOF'
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["six (==1.16.0)"]
[tool.poetry]
package-mode = false
EOF
P="uvx -q poetry@2.5.1"
$P config virtualenvs.in-project true --local
$P lock -q
$P check --lock
sed -i 's/six (==1.16.0)/six (==1.17.0)/' pyproject.toml
$P check --lock
echo "check exit code: $?"
$P lock -q
$P check --lock
grep -A1 '^name = "six"' poetry.lockOutput
All set! Error: pyproject.toml changed significantly since poetry.lock was last generated. Run `poetry lock` to fix the lock file. check exit code: 1 All set! name = "six" version = "1.17.0"
poetry check --lock compares a hash of the relevant parts of pyproject.toml with the one stored in poetry.lock. After the edit it fails with the same message that poetry install prints, pyproject.toml changed significantly since poetry.lock was last generated, and exits with code 1. A plain poetry lock fixes it. The example starts Poetry through uvx poetry@2.5.1; with Poetry installed, use poetry lock and poetry check --lock.
Lock-related commands
| Command | What it does |
|---|---|
| poetry lock | Poetry 2: lock changes, keep the other locked versions |
| poetry lock --regenerate | Poetry 2: rebuild the lock file from scratch (newest allowed versions) |
| poetry lock --no-update | Poetry 1.x only: lock changes without upgrading |
| poetry update | Upgrade every dependency within its constraints, then install |
| poetry update requests | Upgrade one package only |
| poetry update --lock | Upgrade in the lock file without installing |
| poetry check --lock | Fail if poetry.lock does not match pyproject.toml (for CI) |
| poetry install / poetry sync | Install exactly what poetry.lock lists (sync also removes extras) |
Pitfalls
- Merge conflicts in poetry.lock. Do not edit the file by hand. Take either side, then run
poetry lock; it re-resolves only what is needed and rewrites the hash. - Different Poetry versions. Poetry 1.x and 2.x write different lock file formats; a team using both versions keeps rewriting the file. Pin the Poetry version in CI and in the project README.
- No network. Locking needs package metadata from PyPI or your configured sources, even when nothing changes; offline it fails.
- Python constraint. A
requires-pythonwider than a dependency supports makes locking fail; see the error page for supported Python range not compatible.
How to confirm it worked
poetry check --lock prints All set! and exits with 0. git diff poetry.lock shows only the packages your change affected; if every package moved, the lock was regenerated rather than updated.
FAQ
Is poetry lock --no-update still needed?
Not in Poetry 2. Keeping the locked versions is now the default, and the --no-update option was removed. In Poetry 1.x, poetry lock upgraded everything unless you passed --no-update.
How do I upgrade all locked versions?
Run poetry update, which re-resolves every dependency to the newest versions the constraints allow and installs them, or poetry lock --regenerate to rebuild the lock file from scratch without installing.
Should poetry.lock be committed?
Yes for applications, so every machine and CI run installs the same versions. Libraries often commit it too, for reproducible development; it does not affect users who install the library.