Skip to content

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:

$ 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:

$ uv lock --upgrade

To upgrade a single package to the latest version, while retaining the locked versions of all other packages:

$ uv lock --upgrade-package <package>

To upgrade a single package to a specific version:

$ uv lock --upgrade-package <package>==<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.