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

Question

What is the difference between poetry update --lock and 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.

Answer 1

Summary: 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.

Update : Poetry 2.0.0 release :

poetry lock resolves all dependencies and their sub-dependencies in the pyproject.toml file.

(For V2.0.0) : By default, packages that have already been added to the lock file before will not be updated. (source)

--no-update Option no longer exist because poetry lock default option is now similar to a poetry lock --no-update of V1.X (see this for more info)

(For V1.X) : 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.

--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!

Almost. poetry install lazily installs, i.e.:

• If a poetry.lock exists, it just installs the packages specified by the lock file.
• If no poetry.lock exists, it acts like poetry update and tries to resolve dependencies in pyproject.toml, create a poetry.lock, and then installs them.

Thus, poetry install is the same as poetry update if there's no poetry.lock file. It's only slightly 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.