Locking and syncing
Creating the lockfile
The lockfile is created and updated during uv invocations that use the project environment, i.e.,
uv sync
and uv run
. The lockfile may also be explicitly created or updated using uv lock
:
Exporting the lockfile
If you need to integrate uv with other tools or workflows, you can export uv.lock
to
requirements.txt
format with uv export --format requirements-txt
. The generated
requirements.txt
file can then be installed via uv pip install
, or with other tools like pip
.
In general, we recommend against using both a uv.lock
and a requirements.txt
file. If you find
yourself exporting a uv.lock
file, consider opening an issue to discuss your use case.
Checking if the lockfile is up-to-date
To avoid updating the lockfile during uv sync
and uv run
invocations, use the --frozen
flag.
To avoid updating the environment during uv run
invocations, use the --no-sync
flag.
To assert the lockfile matches the project metadata, use the --locked
flag. If the lockfile is not
up-to-date, an error will be raised instead of updating the lockfile.
Upgrading locked package versions
By default, uv will prefer the locked versions of packages when running uv sync
and uv lock
.
Package versions will only change if the project's dependency constraints exclude the previous,
locked version.
To upgrade all packages:
To upgrade a single package to the latest version, while retaining the locked versions of all other packages:
To upgrade a single package to a specific version:
Note
In all cases, upgrades are limited to the project's dependency constraints. For example, if the project defines an upper bound for a package then an upgrade will not go beyond that version.