uv pip sync

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

# 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

src_file

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.

uv pip sync requirements.txt
uv pip sync pylock.toml
echo "requests" | uv pip sync -

Constraints

-c, --constraint

path[]

Constrain package versions during sync.

uv pip sync requirements.txt -c constraints.txt

Environment: UV_CONSTRAINT

-B, --build-constraint

path[]

Constrain build dependencies when building from source.

uv pip sync requirements.txt --build-constraint build-constraints.txt

Environment: UV_BUILD_CONSTRAINT

Optional Dependencies

--extra

string[]

Include optional dependencies (extras) from pylock.toml or pyproject.toml.

uv pip sync pylock.toml --extra dev --extra test

--all-extras

Include all optional dependencies.

uv pip sync pylock.toml --all-extras

--group

string[]

Install dependency groups from pylock.toml or pyproject.toml.

uv pip sync pylock.toml --group dev --group test

Python Environment

-p, --python

string

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

uv pip sync requirements.txt --python 3.11
uv pip sync requirements.txt --python /path/to/python

Environment: UV_PYTHON

--system

Use system Python instead of virtual environment.

Use with caution in CI environments only. Can modify system Python installation.

uv pip sync requirements.txt --system

Environment: UV_SYSTEM_PYTHON

--break-system-packages

Allow installation into externally-managed Python environments.

Intended for CI environments. Use with caution.

Environment: UV_BREAK_SYSTEM_PACKAGES

-t, --target

path

Sync packages to the specified directory.

uv pip sync requirements.txt --target ./libs

--prefix

path

Sync packages to lib, bin folders under the specified directory.

uv pip sync requirements.txt --prefix /opt/myapp

Build Options

--no-build

Don’t build source distributions. Only use pre-built wheels.Alias for --only-binary :all:

uv pip sync requirements.txt --no-build

--no-binary

package[]

Build specific packages from source.

uv pip sync requirements.txt --no-binary numpy
uv pip sync requirements.txt --no-binary :all:

--only-binary

package[]

Only use pre-built wheels for specific packages.

uv pip sync requirements.txt --only-binary pillow
uv pip sync requirements.txt --only-binary :all:

-C, --config-setting

key=value[]

Pass settings to the PEP 517 build backend.

uv pip sync requirements.txt --config-setting="--build-option=--debug"

--config-settings-package

package:key=value[]

Pass package-specific settings to build backends.

uv pip sync requirements.txt --config-settings-package="numpy:--with-lapack"

--no-build-isolation

Disable build isolation. Assumes build dependencies are already installed.

uv pip sync requirements.txt --no-build-isolation

Environment: UV_NO_BUILD_ISOLATION

Index Options

--index

url[]

Package indexes to use (in addition to default).

uv pip sync requirements.txt --index https://pypi.org/simple

Environment: UV_INDEX

--default-index

url

Default package index (replaces PyPI).

uv pip sync requirements.txt --default-index https://private.pypi.org/simple

Environment: UV_DEFAULT_INDEX

-i, --index-url

url

Deprecated: Use --default-index instead.Environment: UV_INDEX_URL

--extra-index-url

url[]

Deprecated: Use --index instead.Environment: UV_EXTRA_INDEX_URL

-f, --find-links

path|url[]

Additional locations to search for packages.

uv pip sync requirements.txt --find-links ./wheels

Environment: UV_FIND_LINKS

--no-index

Ignore package indexes, only use --find-links.

uv pip sync requirements.txt --no-index --find-links ./wheels

--index-strategy

string

Index selection strategy: first-index, unsafe-first-match, or unsafe-best-match.Default: first-indexEnvironment: UV_INDEX_STRATEGY

--keyring-provider

string

Keyring provider for authentication: disabled, subprocess.Default: disabledEnvironment: UV_KEYRING_PROVIDER

Hash Verification

--require-hashes

Require hash verification for all packages.All requirements must include hashes and be pinned to exact versions.

uv pip sync requirements.txt --require-hashes

Environment: UV_REQUIRE_HASHES

--no-verify-hashes

Disable hash verification.Environment: UV_NO_VERIFY_HASHES

Version Constraints

--python-version

version

Minimum Python version to support (e.g., 3.8 or 3.8.17).

uv pip sync requirements.txt --python-version 3.8

--python-platform

triple

Target platform triple (e.g., x86_64-unknown-linux-gnu).

Advanced use case. May install incompatible packages.

uv pip sync requirements.txt --python-platform x86_64-unknown-linux-gnu

Sync Behavior

--allow-empty-requirements

Allow syncing with empty requirements, clearing the environment.

echo "" | uv pip sync - --allow-empty-requirements

--strict

Validate environment after sync, detecting missing dependencies.

uv pip sync requirements.txt --strict

--dry-run

Show sync plan without making changes.

uv pip sync requirements.txt --dry-run

--reinstall

Reinstall all packages, ignoring existing installations.

uv pip sync requirements.txt --reinstall

--reinstall-package

package[]

Reinstall specific packages.

uv pip sync requirements.txt --reinstall-package numpy

--exclude-newer

date

Exclude packages uploaded after the specified date.

uv pip sync requirements.txt --exclude-newer 2024-01-01
uv pip sync requirements.txt --exclude-newer "7 days"

Environment: UV_EXCLUDE_NEWER

--exclude-newer-package

package=date[]

Exclude specific packages uploaded after dates.

uv pip sync requirements.txt --exclude-newer-package "numpy=2024-01-01"

--link-mode

string

Link mode for installations: clone, copy, hardlink, symlink.Default: clone on macOS/Linux, hardlink on WindowsEnvironment: UV_LINK_MODE

--compile-bytecode

Compile Python files to bytecode after installation.

uv pip sync requirements.txt --compile-bytecode

Environment: UV_COMPILE_BYTECODE

uv Extensions

--torch-backend

string

PyTorch backend: cpu, cu126, cu124, cu121, cu118, or auto.

Preview feature. May change in future releases.

uv pip sync requirements.txt --torch-backend cu126

Environment: UV_TORCH_BACKEND

Cache Options

--refresh

Refresh all cached data.

uv pip sync requirements.txt --refresh

--refresh-package

package[]

Refresh cached data for specific packages.

uv pip sync requirements.txt --refresh-package numpy

Examples

Basic Sync

# 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

# 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

# Preview sync changes
uv pip sync requirements.txt --dry-run

Hash Verification

# Require hashes for all packages
uv pip sync requirements.txt --require-hashes

Custom Index

# 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

# 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

# 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):

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

# 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

# Ensure exact environment
uv pip sync requirements.txt --require-hashes

Development Workflow

# Compile during development
uv pip compile pyproject.toml --extra dev -o requirements.txt

# Sync environment
uv pip sync requirements.txt

Docker Images

# Dockerfile
COPY requirements.txt .
RUN uv pip sync requirements.txt --system --compile-bytecode

Cleanup Environments

# Remove all packages not in requirements
uv pip sync requirements.txt

uv pip compile - Generate lockfile
uv pip install - Install packages (keeps existing)
uv sync - Sync project environment

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

uv pip sync

Usage

Arguments

Input Files

Constraints

Optional Dependencies

Python Environment

Build Options

Index Options

Hash Verification

Version Constraints

Sync Behavior

uv Extensions

Cache Options

Examples

Basic Sync

With Extras

Dry Run

Hash Verification

Custom Index

Cross-Platform

Differences from pip install

Exact Sync

Expected Input

Transitive Dependencies

Use Cases

CI/CD Reproducible Builds

Development Workflow

Docker Images

Cleanup Environments

Build docs developers (and LLMs) love

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​Usage

​Arguments

​Input Files

​Constraints

​Optional Dependencies

​Python Environment

​Build Options

​Index Options

​Hash Verification

​Version Constraints

​Sync Behavior

​uv Extensions

​Cache Options

​Examples

​Basic Sync

​With Extras

​Dry Run

​Hash Verification

​Custom Index

​Cross-Platform

​Differences from pip install

​Exact Sync

​Expected Input

​Transitive Dependencies

​Use Cases

​CI/CD Reproducible Builds

​Development Workflow

​Docker Images

​Cleanup Environments

​Related Commands

Build docs developers (and LLMs) love

Usage

Arguments

Input Files

Constraints

Optional Dependencies

Python Environment

Build Options

Index Options

Hash Verification

Version Constraints

Sync Behavior

uv Extensions

Cache Options

Examples

Basic Sync

With Extras

Dry Run

Hash Verification

Custom Index

Cross-Platform

Differences from pip install

Exact Sync

Expected Input

Transitive Dependencies

Use Cases

CI/CD Reproducible Builds

Development Workflow

Docker Images

Cleanup Environments

Related Commands