> ## 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 sync

> Sync the project environment with the lockfile

Update the project's environment to match the lockfile.

## Usage

```bash theme={null}
uv sync [OPTIONS]
```

## Description

Sync ensures that all project dependencies are installed and up-to-date with the lockfile.

By default, an exact sync is performed: uv removes packages that are not declared as dependencies of the project. Use the `--inexact` flag to keep extraneous packages. Note that if an extraneous package conflicts with a project dependency, it will still be removed. Additionally, if `--no-build-isolation` is used, uv will not remove extraneous packages to avoid removing possible build dependencies.

If the project virtual environment (`.venv`) does not exist, it will be created.

The project is re-locked before syncing unless the `--locked` or `--frozen` flag is provided.

uv will search for a project in the current directory or any parent directory. If a project cannot be found, uv will exit with an error.

Note that, when installing from a lockfile, uv will not provide warnings for yanked package versions.

## Options

### Dependency Selection

<ParamField path="--extra" type="string[]">
  Include optional dependencies from the specified extra name.

  May be provided more than once.

  When multiple extras or groups are specified that appear in `tool.uv.conflicts`, uv will report an error.

  Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
</ParamField>

<ParamField path="--all-extras" flag>
  Include all optional dependencies.

  When two or more extras are declared as conflicting in `tool.uv.conflicts`, using this flag will always result in an error.

  Note that all optional dependencies are always included in the resolution; this option only affects the selection of packages to install.
</ParamField>

<ParamField path="--no-extra" type="string[]">
  Exclude the specified optional dependencies, if `--all-extras` is supplied.

  May be provided multiple times.
</ParamField>

<ParamField path="--group" type="string[]">
  Include dependencies from the specified dependency group.

  When multiple extras or groups are specified that appear in `tool.uv.conflicts`, uv will report an error.

  May be provided multiple times.
</ParamField>

<ParamField path="--no-group" type="string[]">
  Disable the specified dependency group.

  This option always takes precedence over default groups, `--all-groups`, and `--group`.

  May be provided multiple times.

  Environment variable: `UV_NO_GROUP`
</ParamField>

<ParamField path="--all-groups" flag>
  Include dependencies from all dependency groups.

  `--no-group` can be used to exclude specific groups.
</ParamField>

<ParamField path="--no-default-groups" flag>
  Ignore the default dependency groups.

  uv includes the groups defined in `tool.uv.default-groups` by default. This disables that option, however, specific groups can still be included with `--group`.

  Environment variable: `UV_NO_DEFAULT_GROUPS`
</ParamField>

<ParamField path="--only-group" type="string[]">
  Only include dependencies from the specified dependency group.

  The project and its dependencies will be omitted.

  May be provided multiple times. Implies `--no-default-groups`.
</ParamField>

<ParamField path="--only-dev" flag>
  Only include the development dependency group.

  The project and its dependencies will be omitted.

  This option is an alias for `--only-group dev`. Implies `--no-default-groups`.
</ParamField>

### Installation Control

<ParamField path="--inexact" flag>
  Do not remove extraneous packages present in the environment.

  When enabled, uv will make the minimum necessary changes to satisfy the requirements. By default, syncing will remove any extraneous packages from the environment.
</ParamField>

<ParamField path="--no-install-project" flag>
  Do not install the current project.

  By default, the current project is installed into the environment with all of its dependencies. The `--no-install-project` option allows the project to be excluded, but all of its dependencies are still installed. This is particularly useful in situations like building Docker images where installing the project separately from its dependencies allows optimal layer caching.
</ParamField>

<ParamField path="--no-install-workspace" flag>
  Do not install any workspace members, including the root project.

  By default, all workspace members and their dependencies are installed into the environment. The `--no-install-workspace` option allows exclusion of all the workspace members while retaining their dependencies.
</ParamField>

<ParamField path="--no-install-local" flag>
  Do not install local path dependencies.

  Skips the current project, workspace members, and any other local (path or editable) packages. Only remote/indexed dependencies are installed. Useful in Docker builds to cache heavy third-party dependencies first and layer local packages separately.
</ParamField>

<ParamField path="--no-install-package" type="string[]">
  Do not install the given package(s).

  By default, all of the project's dependencies are installed into the environment. The `--no-install-package` option allows exclusion of specific packages. Note this can result in a broken environment, and should be used with caution.
</ParamField>

<ParamField path="--no-editable" flag>
  Install any editable dependencies, including the project and any workspace members, as non-editable.

  Environment variable: `UV_NO_EDITABLE`
</ParamField>

### Locking Options

<ParamField path="--locked" flag>
  Assert that the `uv.lock` will remain unchanged.

  Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.

  Environment variable: `UV_LOCKED`
</ParamField>

<ParamField path="--frozen" flag>
  Sync without updating the `uv.lock` file.

  Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the `pyproject.toml` includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.

  Environment variable: `UV_FROZEN`
</ParamField>

### Workspace Options

<ParamField path="--all-packages" flag>
  Sync all packages in the workspace.

  The workspace's environment (`.venv`) is updated to include all workspace members.

  Any extras or groups specified via `--extra`, `--group`, or related options will be applied to all workspace members.
</ParamField>

<ParamField path="--package" type="string[]">
  Sync for specific packages in the workspace.

  The workspace's environment (`.venv`) is updated to reflect the subset of dependencies declared by the specified workspace member packages.

  If any workspace member does not exist, uv will exit with an error.
</ParamField>

<ParamField path="--script" type="path">
  Sync the environment for a Python script, rather than the current project.

  If provided, uv will sync the dependencies based on the script's inline metadata table, in adherence with PEP 723.
</ParamField>

### Environment Options

<ParamField path="--active" flag>
  Sync dependencies to the active virtual environment.

  Instead of creating or updating the virtual environment for the project or script, the active virtual environment will be preferred, if the `VIRTUAL_ENV` environment variable is set.
</ParamField>

<ParamField path="--python" type="string">
  The Python interpreter to use for the project environment.

  By default, the first interpreter that meets the project's `requires-python` constraint is used.

  If a Python interpreter in a virtual environment is provided, the packages will not be synced to the given environment. The interpreter will be used to create a virtual environment in the project.

  See `uv help python` for details on Python discovery and supported request formats.

  Short form: `-p`\
  Environment variable: `UV_PYTHON`
</ParamField>

<ParamField path="--python-platform" type="string">
  The platform for which requirements should be installed.

  Represented as a "target triple", a string that describes the target platform in terms of its CPU, vendor, and operating system name, like `x86_64-unknown-linux-gnu` or `aarch64-apple-darwin`.

  WARNING: When specified, uv will select wheels that are compatible with the target platform; as a result, the installed distributions may not be compatible with the current platform.
</ParamField>

### Output Options

<ParamField path="--output-format" type="string" default="text">
  Select the output format.

  Options:

  * `text` - Display the result in a human-readable format
  * `json` - Display the result in JSON format
</ParamField>

### Validation Options

<ParamField path="--check" flag>
  Check if the Python environment is synchronized with the project.

  If the environment is not up to date, uv will exit with an error.
</ParamField>

<ParamField path="--dry-run" flag>
  Perform a dry run, without writing the lockfile or modifying the project environment.

  In dry-run mode, uv will resolve the project's dependencies and report on the resulting changes to both the lockfile and the project environment, but will not modify either.
</ParamField>

## Examples

### Basic sync

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

Syncs the project environment with the lockfile, creating the environment if needed.

### Sync with extras

```bash theme={null}
uv sync --extra dev --extra test
```

Syncs including optional dependencies from the `dev` and `test` extras.

### Sync all extras

```bash theme={null}
uv sync --all-extras
```

### Sync only development dependencies

```bash theme={null}
uv sync --only-dev
```

Installs only the development dependencies, excluding the project and its runtime dependencies.

### Sync with frozen lockfile

```bash theme={null}
uv sync --frozen
```

Syncs using the existing lockfile without updating it. Fails if the lockfile is missing.

### Sync without removing packages

```bash theme={null}
uv sync --inexact
```

Installs required packages but doesn't remove extraneous ones.

### Sync all workspace packages

```bash theme={null}
uv sync --all-packages
```

### Sync specific workspace packages

```bash theme={null}
uv sync --package pkg1 --package pkg2
```

### Sync for a Python script

```bash theme={null}
uv sync --script my_script.py
```

Syncs dependencies based on the script's PEP 723 inline metadata.

### Check sync status

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

Checks if the environment is synchronized without making changes.

### Dry run

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

Shows what would be changed without actually modifying anything.

## Common Patterns

### Docker layer caching

Install dependencies first, then the project:

```dockerfile theme={null}
# Copy only dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies (cached layer)
RUN uv sync --no-install-project

# Copy project code
COPY . .

# Install project
RUN uv sync
```

### Sync with specific dependency groups

```bash theme={null}
# Include specific groups
uv sync --group test --group docs

# Exclude specific groups
uv sync --all-groups --no-group heavy
```

### Local development workflow

```bash theme={null}
# Sync with all extras and dev dependencies
uv sync --all-extras
```

### CI/CD workflow

```bash theme={null}
# Ensure lockfile is up to date
uv sync --locked
```

### Install only third-party packages

```bash theme={null}
# Skip local packages (useful for Docker caching)
uv sync --no-install-local
```

## Related Commands

* [`uv lock`](/cli/lock) - Update the project lockfile
* [`uv add`](/cli/add) - Add dependencies to the project
* [`uv remove`](/cli/remove) - Remove dependencies from the project
* [`uv run`](/cli/run) - Run a command in the project environment