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

> Sync an environment with a lockfile.

`uv pip sync` synchronizes a Python environment to exactly match a requirements file or lockfile. Unlike `uv pip install`, it removes packages that aren't in the file.

## Usage

```bash theme={null}
# Sync with requirements file
uv pip sync requirements.txt

# Sync with pylock.toml
uv pip sync pylock.toml

# Sync multiple files
uv pip sync requirements.txt dev-requirements.txt
```

## Arguments

### Input Files

<ParamField body="src_file" type="path[]" required>
  Files to sync from.

  Supported formats:

  * `requirements.txt`
  * `.py` files with inline metadata
  * `pylock.toml`
  * `pyproject.toml`, `setup.py`, `setup.cfg`

  Use `-` to read from stdin.

  ```bash theme={null}
  uv pip sync requirements.txt
  uv pip sync pylock.toml
  echo "requests" | uv pip sync -
  ```
</ParamField>

### Constraints

<ParamField body="-c, --constraint" type="path[]">
  Constrain package versions during sync.

  ```bash theme={null}
  uv pip sync requirements.txt -c constraints.txt
  ```

  Environment: `UV_CONSTRAINT`
</ParamField>

<ParamField body="-B, --build-constraint" type="path[]">
  Constrain build dependencies when building from source.

  ```bash theme={null}
  uv pip sync requirements.txt --build-constraint build-constraints.txt
  ```

  Environment: `UV_BUILD_CONSTRAINT`
</ParamField>

### Optional Dependencies

<ParamField body="--extra" type="string[]">
  Include optional dependencies (extras) from `pylock.toml` or `pyproject.toml`.

  ```bash theme={null}
  uv pip sync pylock.toml --extra dev --extra test
  ```
</ParamField>

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

  ```bash theme={null}
  uv pip sync pylock.toml --all-extras
  ```
</ParamField>

<ParamField body="--group" type="string[]">
  Install dependency groups from `pylock.toml` or `pyproject.toml`.

  ```bash theme={null}
  uv pip sync pylock.toml --group dev --group test
  ```
</ParamField>

### Python Environment

<ParamField body="-p, --python" type="string">
  Python interpreter to use.

  By default, syncing requires a virtual environment. Use with caution for system Python.

  ```bash theme={null}
  uv pip sync requirements.txt --python 3.11
  uv pip sync requirements.txt --python /path/to/python
  ```

  Environment: `UV_PYTHON`
</ParamField>

<ParamField body="--system">
  Use system Python instead of virtual environment.

  <Warning>
    Use with caution in CI environments only. Can modify system Python installation.
  </Warning>

  ```bash theme={null}
  uv pip sync requirements.txt --system
  ```

  Environment: `UV_SYSTEM_PYTHON`
</ParamField>

<ParamField body="--break-system-packages">
  Allow installation into externally-managed Python environments.

  <Warning>
    Intended for CI environments. Use with caution.
  </Warning>

  Environment: `UV_BREAK_SYSTEM_PACKAGES`
</ParamField>

<ParamField body="-t, --target" type="path">
  Sync packages to the specified directory.

  ```bash theme={null}
  uv pip sync requirements.txt --target ./libs
  ```
</ParamField>

<ParamField body="--prefix" type="path">
  Sync packages to lib, bin folders under the specified directory.

  ```bash theme={null}
  uv pip sync requirements.txt --prefix /opt/myapp
  ```
</ParamField>

### Build Options

<ParamField body="--no-build">
  Don't build source distributions. Only use pre-built wheels.

  Alias for `--only-binary :all:`

  ```bash theme={null}
  uv pip sync requirements.txt --no-build
  ```
</ParamField>

<ParamField body="--no-binary" type="package[]">
  Build specific packages from source.

  ```bash theme={null}
  uv pip sync requirements.txt --no-binary numpy
  uv pip sync requirements.txt --no-binary :all:
  ```
</ParamField>

<ParamField body="--only-binary" type="package[]">
  Only use pre-built wheels for specific packages.

  ```bash theme={null}
  uv pip sync requirements.txt --only-binary pillow
  uv pip sync requirements.txt --only-binary :all:
  ```
</ParamField>

<ParamField body="-C, --config-setting" type="key=value[]">
  Pass settings to the PEP 517 build backend.

  ```bash theme={null}
  uv pip sync requirements.txt --config-setting="--build-option=--debug"
  ```
</ParamField>

<ParamField body="--config-settings-package" type="package:key=value[]">
  Pass package-specific settings to build backends.

  ```bash theme={null}
  uv pip sync requirements.txt --config-settings-package="numpy:--with-lapack"
  ```
</ParamField>

<ParamField body="--no-build-isolation">
  Disable build isolation. Assumes build dependencies are already installed.

  ```bash theme={null}
  uv pip sync requirements.txt --no-build-isolation
  ```

  Environment: `UV_NO_BUILD_ISOLATION`
</ParamField>

### Index Options

<ParamField body="--index" type="url[]">
  Package indexes to use (in addition to default).

  ```bash theme={null}
  uv pip sync requirements.txt --index https://pypi.org/simple
  ```

  Environment: `UV_INDEX`
</ParamField>

<ParamField body="--default-index" type="url">
  Default package index (replaces PyPI).

  ```bash theme={null}
  uv pip sync requirements.txt --default-index https://private.pypi.org/simple
  ```

  Environment: `UV_DEFAULT_INDEX`
</ParamField>

<ParamField body="-i, --index-url" type="url">
  Deprecated: Use `--default-index` instead.

  Environment: `UV_INDEX_URL`
</ParamField>

<ParamField body="--extra-index-url" type="url[]">
  Deprecated: Use `--index` instead.

  Environment: `UV_EXTRA_INDEX_URL`
</ParamField>

<ParamField body="-f, --find-links" type="path|url[]">
  Additional locations to search for packages.

  ```bash theme={null}
  uv pip sync requirements.txt --find-links ./wheels
  ```

  Environment: `UV_FIND_LINKS`
</ParamField>

<ParamField body="--no-index">
  Ignore package indexes, only use `--find-links`.

  ```bash theme={null}
  uv pip sync requirements.txt --no-index --find-links ./wheels
  ```
</ParamField>

<ParamField body="--index-strategy" type="string">
  Index selection strategy: `first-index`, `unsafe-first-match`, or `unsafe-best-match`.

  Default: `first-index`

  Environment: `UV_INDEX_STRATEGY`
</ParamField>

<ParamField body="--keyring-provider" type="string">
  Keyring provider for authentication: `disabled`, `subprocess`.

  Default: `disabled`

  Environment: `UV_KEYRING_PROVIDER`
</ParamField>

### Hash Verification

<ParamField body="--require-hashes">
  Require hash verification for all packages.

  All requirements must include hashes and be pinned to exact versions.

  ```bash theme={null}
  uv pip sync requirements.txt --require-hashes
  ```

  Environment: `UV_REQUIRE_HASHES`
</ParamField>

<ParamField body="--no-verify-hashes">
  Disable hash verification.

  Environment: `UV_NO_VERIFY_HASHES`
</ParamField>

### Version Constraints

<ParamField body="--python-version" type="version">
  Minimum Python version to support (e.g., `3.8` or `3.8.17`).

  ```bash theme={null}
  uv pip sync requirements.txt --python-version 3.8
  ```
</ParamField>

<ParamField body="--python-platform" type="triple">
  Target platform triple (e.g., `x86_64-unknown-linux-gnu`).

  <Warning>
    Advanced use case. May install incompatible packages.
  </Warning>

  ```bash theme={null}
  uv pip sync requirements.txt --python-platform x86_64-unknown-linux-gnu
  ```
</ParamField>

### Sync Behavior

<ParamField body="--allow-empty-requirements">
  Allow syncing with empty requirements, clearing the environment.

  ```bash theme={null}
  echo "" | uv pip sync - --allow-empty-requirements
  ```
</ParamField>

<ParamField body="--strict">
  Validate environment after sync, detecting missing dependencies.

  ```bash theme={null}
  uv pip sync requirements.txt --strict
  ```
</ParamField>

<ParamField body="--dry-run">
  Show sync plan without making changes.

  ```bash theme={null}
  uv pip sync requirements.txt --dry-run
  ```
</ParamField>

<ParamField body="--reinstall">
  Reinstall all packages, ignoring existing installations.

  ```bash theme={null}
  uv pip sync requirements.txt --reinstall
  ```
</ParamField>

<ParamField body="--reinstall-package" type="package[]">
  Reinstall specific packages.

  ```bash theme={null}
  uv pip sync requirements.txt --reinstall-package numpy
  ```
</ParamField>

<ParamField body="--exclude-newer" type="date">
  Exclude packages uploaded after the specified date.

  ```bash theme={null}
  uv pip sync requirements.txt --exclude-newer 2024-01-01
  uv pip sync requirements.txt --exclude-newer "7 days"
  ```

  Environment: `UV_EXCLUDE_NEWER`
</ParamField>

<ParamField body="--exclude-newer-package" type="package=date[]">
  Exclude specific packages uploaded after dates.

  ```bash theme={null}
  uv pip sync requirements.txt --exclude-newer-package "numpy=2024-01-01"
  ```
</ParamField>

<ParamField body="--link-mode" type="string">
  Link mode for installations: `clone`, `copy`, `hardlink`, `symlink`.

  Default: `clone` on macOS/Linux, `hardlink` on Windows

  Environment: `UV_LINK_MODE`
</ParamField>

<ParamField body="--compile-bytecode">
  Compile Python files to bytecode after installation.

  ```bash theme={null}
  uv pip sync requirements.txt --compile-bytecode
  ```

  Environment: `UV_COMPILE_BYTECODE`
</ParamField>

### uv Extensions

<ParamField body="--torch-backend" type="string">
  PyTorch backend: `cpu`, `cu126`, `cu124`, `cu121`, `cu118`, or `auto`.

  <Info>
    Preview feature. May change in future releases.
  </Info>

  ```bash theme={null}
  uv pip sync requirements.txt --torch-backend cu126
  ```

  Environment: `UV_TORCH_BACKEND`
</ParamField>

### Cache Options

<ParamField body="--refresh">
  Refresh all cached data.

  ```bash theme={null}
  uv pip sync requirements.txt --refresh
  ```
</ParamField>

<ParamField body="--refresh-package" type="package[]">
  Refresh cached data for specific packages.

  ```bash theme={null}
  uv pip sync requirements.txt --refresh-package numpy
  ```
</ParamField>

## Examples

### Basic Sync

```bash theme={null}
# Sync with requirements.txt
uv pip sync requirements.txt

# Sync with pylock.toml
uv pip sync pylock.toml

# Sync multiple files
uv pip sync requirements.txt dev-requirements.txt
```

### With Extras

```bash theme={null}
# Sync with specific extras
uv pip sync pylock.toml --extra dev

# Sync with all extras
uv pip sync pylock.toml --all-extras

# Multiple extras
uv pip sync pylock.toml --extra dev --extra test
```

### Dry Run

```bash theme={null}
# Preview sync changes
uv pip sync requirements.txt --dry-run
```

### Hash Verification

```bash theme={null}
# Require hashes for all packages
uv pip sync requirements.txt --require-hashes
```

### Custom Index

```bash theme={null}
# Use private index
uv pip sync requirements.txt --index https://private.pypi.org/simple

# Multiple indexes
uv pip sync requirements.txt --index https://pypi.org/simple --index https://private.pypi.org/simple
```

### Cross-Platform

```bash theme={null}
# Sync for specific Python version
uv pip sync requirements.txt --python-version 3.8

# Sync for specific platform
uv pip sync requirements.txt --python-platform x86_64-unknown-linux-gnu
```

## Differences from pip install

`uv pip sync` differs from `uv pip install` in key ways:

### Exact Sync

```bash theme={null}
# pip install: Adds packages, keeps existing
uv pip install -r requirements.txt

# pip sync: Removes extraneous packages
uv pip sync requirements.txt
```

### Expected Input

`uv pip sync` expects a fully resolved file (from `uv pip compile` or `uv export`):

```bash theme={null}
# Step 1: Generate lockfile
uv pip compile requirements.in -o requirements.txt

# Step 2: Sync to lockfile
uv pip sync requirements.txt
```

### Transitive Dependencies

If the input file is missing transitive dependencies, they won't be installed:

```bash theme={null}
# requirements.txt (incomplete)
requests==2.31.0
# Missing: certifi, charset-normalizer, idna, urllib3

# Sync will only install requests, which may break
uv pip sync requirements.txt  # Warning: missing dependencies

# Use --strict to detect issues
uv pip sync requirements.txt --strict
```

## Use Cases

### CI/CD Reproducible Builds

```bash theme={null}
# Ensure exact environment
uv pip sync requirements.txt --require-hashes
```

### Development Workflow

```bash theme={null}
# Compile during development
uv pip compile pyproject.toml --extra dev -o requirements.txt

# Sync environment
uv pip sync requirements.txt
```

### Docker Images

```dockerfile theme={null}
# Dockerfile
COPY requirements.txt .
RUN uv pip sync requirements.txt --system --compile-bytecode
```

### Cleanup Environments

```bash theme={null}
# Remove all packages not in requirements
uv pip sync requirements.txt
```

## Related Commands

* [`uv pip compile`](/cli/pip-compile) - Generate lockfile
* [`uv pip install`](/cli/pip-install) - Install packages (keeps existing)
* [`uv sync`](/cli/sync) - Sync project environment