What is the difference between `poetry lock` and `poetry update --lock`?

user_5209439 0
Viewed 492

I would like to understand what is the difference between poetry update --lock vs poetry lock. I wasn't able to find much useful hints in the official docs and I know that both are not the same since we recently had to switch from poetry update --lock to poetry lock for upgrading packages because of unexpected issues.

python-poetry python
1 Answers

TLDR; you're not updating packages in poetry.lock file anymore.

poetry lock creates a poetry.lock file, but does not install packages.

(poetry lock --help description):

The lock command reads the pyproject.toml file from the current directory, processes it, and locks the dependencies in the poetry.lock file.

"Processing" means resolving dependencies to be compatible, (by default, with latest versions). poetry lock does NOT install packages, it just generates a poetry.lock file.

Let's say I have package A and it has sub-dependency B.

  1. poetry lock resolves all dependencies and their sub-dependencies in the pyproject.toml file.
  2. By default, it will try to update all the sub-dependency versions. So it'll try to update the latest version of A and the latest version of B.
  3. --no-update will prevent any updates. Instead, Poetry will focus on making the pyproject.toml versions compatible, but will use whatever versions are compatible with the currently existing versions in the pyproject.toml. That means even though Package A is compatible with the latest version of package B, it will not update package B, it will just make sure that some compatible package B is used.

poetry update also updates the package versions and then installs the updates.

  1. Resolves dependencies to be compatible with each other, just like poetry lock
  2. Creates or updates poetry.lock like poetry lock
  3. Installs the packages, which is different. The documentation doesn't explicitly mention this, but you can infer from the description for --lock flag, which does not perform an install, but just updates poetry.lock

From the documentation linked above:

--lock : Do not perform install (only update the lockfile).

Notice that updating not only installs a new package, but also updates several packages.

$ poetry update
Updating dependencies
Resolving dependencies... (106.7s)

Writing lock file

Package operations: 1 install, 39 updates, 0 removals

Wait, but that basically just sounds like poetry install!

poetry install lazily installs. It first checks if a poetry.lock exists, and if it already exists, it just installs those.

If no poetry.lock exists, it acts like poetry update and tries to resolve dependencies in pyproject.toml, create a poetry.lock, and then install them.

poetry install is the same as poetry update if there's no poetry.lock file. It's only minorly more convenient to install directly from the poetry.lock file if you don't want to update dependencies.

My experience has been: just use poetry update unless you have a very specific circumstance. In your case, there was probably some package that couldn't be updated because that version was explicitly being used, and upgrading would cause something to break in a hard-to-fix way.

user_31215480
Related