poetry-lock

Lock dependencies from the current directory's pyproject.toml file

$ poetry lock

$ poetry lock --regenerate

poetry lock [<options>]

--no-update
    Do not update locked versions, only check the lock file. This option implies --check.

--check
    Only check if the poetry.lock file is up to date with pyproject.toml. If it's not, an error will be raised. No changes are written.

--no-interaction
    Do not ask any interactive question during the locking process.

--directory (-C)
    The working directory where the pyproject.toml file is located. This allows executing the command from a different directory.

The poetry lock command is a fundamental tool within the Poetry dependency management ecosystem, designed to ensure reproducible project environments. Its primary function is to resolve the exact versions of all direct and transitive dependencies specified in a project's pyproject.toml file and record them in a poetry.lock file. This lock file acts as a snapshot, guaranteeing that anyone working on the project will install the identical set of package versions, thereby preventing "it works on my machine" scenarios caused by varying dependency versions.

When executed without options, poetry lock will attempt to find the latest compatible versions for all dependencies and update the poetry.lock file accordingly. This process involves querying package repositories, performing dependency resolution, and then meticulously writing the precise package names, versions, and their hashes into the lock file. This command is implicitly called by other Poetry commands like poetry add, poetry remove, and poetry update, which modify the project's dependency graph. However, poetry lock can be run explicitly to refresh or generate the lock file independently of other actions. It is crucial for maintaining a consistent and reliable development and deployment workflow across different environments.

poetry lock relies heavily on the definitions within your pyproject.toml file.
Complex dependency graphs can lead to longer resolution times, especially the first time.
Requires network access to package repositories for initial resolution and updates (unless packages are cached).
Can fail if an unresolvable conflict exists within your declared dependencies or if package sources are unreachable.

While many Poetry commands (like add, remove, update) automatically trigger a lock file update, you might run poetry lock explicitly if you've manually edited pyproject.toml and need to refresh the lock file without performing other actions like installing dependencies. It's also useful for CI/CD pipelines to ensure the lock file is always current after source code changes.

The poetry.lock file records the exact package versions and their hashes that were resolved. This ensures that every developer and deployment environment uses precisely the same dependencies, guaranteeing consistency and preventing unexpected breakage due to version drift. It should always be committed to version control.

The concept of a lock file for reproducible builds is central to the Poetry project, which was initiated to modernize Python dependency management. poetry lock, as a dedicated command, has been an integral part of Poetry since its early development. It embodies Poetry's philosophy of ensuring consistent dependency environments, a significant improvement over traditional methods that often led to environment inconsistencies. Its continuous refinement reflects ongoing efforts to enhance resolution speed and robustness.

poetry(1), poetry install(1), poetry update(1), poetry add(1), poetry remove(1), pip(1)