Skip to main content
Update the project’s lockfile (uv.lock).

​
Usage

uv lock [OPTIONS]

​
Description

Update the project’s lockfile. If the project lockfile (uv.lock) does not exist, it will be created. If a lockfile is present, its contents will be used as preferences for the resolution. If there are no changes to the project’s dependencies, locking will have no effect unless the --upgrade flag is provided.

​
Options

​
Validation Options

​
--check
Check if the lockfile is up-to-date.Asserts that the uv.lock would remain unchanged after a resolution. If the lockfile is missing or needs to be updated, uv will exit with an error.Equivalent to --locked.
​
--locked
Check if the lockfile is up-to-date.Asserts that the uv.lock would remain unchanged after a resolution. If the lockfile is missing or needs to be updated, uv will exit with an error.Equivalent to --check.Environment variable: UV_LOCKED
​
--check-exists
Assert that a uv.lock exists without checking if it is up-to-date.Equivalent to --frozen.Environment variable: UV_FROZEN
​
--dry-run
Perform a dry run, without writing the lockfile.In dry-run mode, uv will resolve the project’s dependencies and report on the resulting changes, but will not write the lockfile to disk.

​
Script Options

​
--script
path
Lock the specified Python script, rather than the current project.If provided, uv will lock the script (based on its inline metadata table, in adherence with PEP 723) to a .lock file adjacent to the script itself.

​
Python Options

​
--python
string
The Python interpreter to use during resolution.A Python interpreter is required for building source distributions to determine package metadata when there are not wheels.The interpreter is also used as the fallback value for the minimum Python version if requires-python is not set.See uv help python for details on Python discovery and supported request formats.Short form: -p
Environment variable: UV_PYTHON

​
Examples

​
Create or update the lockfile

uv lock
Resolves project dependencies and writes them to uv.lock.

​
Check if lockfile is up-to-date

uv lock --check
Exits with an error if the lockfile is missing or needs to be updated. 
uv lock --locked
Equivalent to --check.

​
Verify lockfile exists

uv lock --check-exists
Verifies that uv.lock exists without checking if it’s up-to-date.

​
Dry run

uv lock --dry-run
Resolves dependencies and shows what would change without writing the lockfile.

​
Lock a Python script

uv lock --script my_script.py
Creates a my_script.lock file adjacent to the script based on its PEP 723 inline metadata.

​
Lock with a specific Python version

uv lock --python 3.11
Uses Python 3.11 for resolution and as the minimum Python version.

​
Common Patterns

​
CI/CD: Ensure lockfile is current

uv lock --check
In CI, this ensures developers have committed an up-to-date lockfile.

​
Development: Preview lockfile changes

uv lock --dry-run
See what would change before committing to it.

​
Upgrade dependencies

To upgrade dependencies, use the upgrade flags from the resolver: 
uv lock --upgrade
Upgrades all dependencies to their latest compatible versions. 
uv lock --upgrade-package requests
Upgrades only the requests package.

​
Lock after adding dependencies

When you add dependencies via pyproject.toml directly: 
# Edit pyproject.toml manually
vi pyproject.toml

# Update lockfile
uv lock
Note: uv add automatically updates the lockfile, so this is only needed when editing pyproject.toml manually.

​
Cross-platform lockfiles

Lockfiles are cross-platform by default. When you run uv lock, it creates a lockfile that works on all platforms (Linux, macOS, Windows) and all Python versions compatible with your requires-python constraint. 
# Create a universal lockfile
uv lock

# The same lockfile works on all platforms
git commit uv.lock

​
Monorepo: Lock entire workspace

# From workspace root
uv lock
Locks all workspace members together in a single uv.lock file.
  • uv sync - Sync the environment with the lockfile
  • uv add - Add dependencies (automatically updates lockfile)
  • uv remove - Remove dependencies (automatically updates lockfile)
  • uv tree - Display the dependency tree

Build docs developers (and LLMs) love

Get started for freeTalk to us