Yes for applications: commit poetry.lock so every developer, CI job and production deploy installs the same versions. For libraries, Poetry's own documentation notes that an installing application ignores your lock file, so the lock mainly steadies your own development and test runs.
What the lock file does
When Poetry installs and no lock file exists, it resolves dependencies from your project file, downloads the latest matching versions, and writes the exact versions into the lock file. On later installs it uses the lock file, so a teammate gets the same packages even if newer ones have been published. Poetry's documentation says this can mean older versions than the newest, and that this is by design, to avoid surprise breakage.
Applications and libraries
| Project type | Commit the lock? | Reason |
|---|---|---|
| Application or service | Yes | Reproducible builds, same versions everywhere |
| Library others install | Your call | Users ignore it, but it stabilises your tests |
| Internal tool | Yes | Treat as an application |
Poetry's guide says application developers commit the lock for more reproducible builds. For libraries it notes that an installing application ignores the library's lock file, and describes omitting it as a simple option, at some cost to reproducibility. Its alternative is to refresh the lock file regularly.
Updating on purpose
The update command fetches the latest versions that match your project file and rewrites the lock file. The documentation describes it as equivalent to deleting the lock and installing again. This is the moment to review changes, not a background event.
A reasonable routine:
- Run the update on a branch.
- Read the diff of the lock file for new or removed packages.
- Run tests and your vulnerability scan.
- Merge only if both pass.
What a stale lock looks like
If the lock file and the project file disagree, Poetry shows a warning during install. Do not ignore it in CI. A lock that no longer matches the project means the build is not testing what you think it is.
Review the lock diff, not only the project file
A change to the project file is usually one line. The matching change in the lock file can be dozens of lines, because one new direct dependency may bring several new transitive packages. That is where a surprise hides. When reading a pull request, look at which packages were added, which versions changed, and whether any new package is one nobody on the team has heard of.
Pair that review with an automated scan, so known vulnerable versions are caught even when the diff is long.
Try it yourself
Click through it at your own pace, or open it full screen. See how a pull request that changes dependencies can be checked before merge.
Quick check
Does a lock file make my app safe?
No. It makes installs repeatable. You still need to scan the pinned versions for known issues.
Why does Poetry install older versions than the newest?
It follows the lock file on purpose, so unexpected updates do not break the project.
Safeguard's policies and gates can check a pull request that changes a lock file. A free scan shows what is in yours today.
Sources
Last reviewed: 19 October 2026.
