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

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

Environment: UV_INDEX_STRATEGY

--keyring-provider · string

Keyring provider for authentication: disabled, subprocess.

Default: disabled

Environment: 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 Windows

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

Related Commands

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