> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv lock

> Update the project's lockfile

Update the project's lockfile (`uv.lock`).

## Usage

```bash theme={null}
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

<ParamField path="--check" flag>
  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`.
</ParamField>

<ParamField path="--locked" flag>
  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`
</ParamField>

<ParamField path="--check-exists" flag>
  Assert that a `uv.lock` exists without checking if it is up-to-date.

  Equivalent to `--frozen`.

  Environment variable: `UV_FROZEN`
</ParamField>

<ParamField path="--dry-run" flag>
  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.
</ParamField>

### Script Options

<ParamField path="--script" type="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.
</ParamField>

### Python Options

<ParamField path="--python" type="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`
</ParamField>

## Examples

### Create or update the lockfile

```bash theme={null}
uv lock
```

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

### Check if lockfile is up-to-date

```bash theme={null}
uv lock --check
```

Exits with an error if the lockfile is missing or needs to be updated.

```bash theme={null}
uv lock --locked
```

Equivalent to `--check`.

### Verify lockfile exists

```bash theme={null}
uv lock --check-exists
```

Verifies that `uv.lock` exists without checking if it's up-to-date.

### Dry run

```bash theme={null}
uv lock --dry-run
```

Resolves dependencies and shows what would change without writing the lockfile.

### Lock a Python script

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
uv lock --check
```

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

### Development: Preview lockfile changes

```bash theme={null}
uv lock --dry-run
```

See what would change before committing to it.

### Upgrade dependencies

To upgrade dependencies, use the upgrade flags from the resolver:

```bash theme={null}
uv lock --upgrade
```

Upgrades all dependencies to their latest compatible versions.

```bash theme={null}
uv lock --upgrade-package requests
```

Upgrades only the `requests` package.

### Lock after adding dependencies

When you add dependencies via `pyproject.toml` directly:

```bash theme={null}
# 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.

```bash theme={null}
# Create a universal lockfile
uv lock

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

### Monorepo: Lock entire workspace

```bash theme={null}
# From workspace root
uv lock
```

Locks all workspace members together in a single `uv.lock` file.

## Related Commands

* [`uv sync`](/cli/sync) - Sync the environment with the lockfile
* [`uv add`](/cli/add) - Add dependencies (automatically updates lockfile)
* [`uv remove`](/cli/remove) - Remove dependencies (automatically updates lockfile)
* [`uv tree`](/cli/tree) - Display the dependency tree