CODEWITHSUNDEEP
pythonpython-poetry
Arijit Basu
Arijit Basu

Reputation: 431

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

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.

Upvotes: 33

Views: 34118

Answers (2)

Dave Liu
Dave Liu

Reputation: 1142

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

Upvotes: 31

Akaisteph7
Akaisteph7

Reputation: 6534

When called with no other arguments, they do the same thing.

If you check the source code, you will see they both end up calling the same function (def run) for updating the lock file. Prior to that, they both call def execute_operations with argument False to avoid actually installing anything.

The Difference

The only thing that is different is what other options you can pass while calling those commands. Those can affect what you're trying to do. You can see these extra options in the docs.

  • poetry lock: --no-update (source code)
  • poetry update --lock: packages --without --with --only --dry-run (source code)

Examples

So, for example, you could create/update the lock file without updating any packages previously pinned in pyproject.toml or updating any pinned version in poetry.lock to its latest version only by using the following command:

poetry lock --no-update

Similarly, you could update a specific package version just in the lock file only by using the following command:

poetry update [package] --lock

Or you could test a lock file update by running it in dry-run mode only by using the following command:

poetry update --lock --dry-run

You might also think you could update just the lock file's dev dependencies by using the following command:

poetry update --lock --only=dev

but as of 1.6, that just doesn't work for whatever reason.

Upvotes: 8

Related Questions