uv pip compile

uv pip compile resolves dependencies and creates a locked requirements file. It is compatible with pip-compile from pip-tools but offers significantly faster performance.

Usage

# Compile requirements
uv pip compile requirements.in -o requirements.txt

# Compile pyproject.toml
uv pip compile pyproject.toml -o requirements.txt

# Compile with extras
uv pip compile pyproject.toml --extra dev -o requirements.txt

# Upgrade all packages
uv pip compile requirements.in --upgrade -o requirements.txt

Arguments

Input Sources

src_file

path[]

required

Input files to compile.Supported formats:

requirements.in or .txt
.py files with inline metadata
pylock.toml
pyproject.toml, setup.py, setup.cfg

Use - to read from stdin.

uv pip compile requirements.in
uv pip compile pyproject.toml setup.cfg
echo "requests" | uv pip compile -

Output Options

-o, --output-file

path

Write compiled requirements to a file.If the file exists, its pinned versions are used as preferences during resolution (unless --upgrade is specified).

uv pip compile requirements.in -o requirements.txt
uv pip compile pyproject.toml -o requirements.txt

--format

string

Output format: requirements-txt or pylock.Default: Inferred from --output-file extension, otherwise requirements-txt

uv pip compile requirements.in --format pylock -o pylock.toml

Constraints and Overrides

-c, --constraint

path[]

Constrain package versions without requiring installation.

uv pip compile requirements.in -c constraints.txt

Environment: UV_CONSTRAINT

--override

path[]

Override package versions, ignoring dependencies.

uv pip compile requirements.in --override overrides.txt

Environment: UV_OVERRIDE

--exclude

path[]

Exclude packages from resolution.

uv pip compile requirements.in --exclude excludes.txt

Environment: UV_EXCLUDE

-B, --build-constraint

path[]

Constrain build dependencies when building from source.

uv pip compile requirements.in --build-constraint build-constraints.txt

Environment: UV_BUILD_CONSTRAINT

Optional Dependencies

--extra

string[]

Include optional dependencies (extras) from pyproject.toml.

uv pip compile pyproject.toml --extra dev --extra test

--all-extras

Include all optional dependencies.

uv pip compile pyproject.toml --all-extras

--group

string[]

Include dependency groups from pyproject.toml.

uv pip compile pyproject.toml --group dev --group test

Resolver Options

-U, --upgrade

Upgrade all packages to the latest compatible versions.

uv pip compile requirements.in --upgrade

-P, --upgrade-package

requirement[]

Upgrade specific packages while keeping others pinned.

uv pip compile requirements.in --upgrade-package requests --upgrade-package flask

--resolution

string

Resolution strategy: highest, lowest, or lowest-direct.Default: highest

uv pip compile requirements.in --resolution lowest

Environment: UV_RESOLUTION

--prerelease

string

Pre-release handling: disallow, allow, if-necessary, explicit, or if-necessary-or-explicit.Default: if-necessary-or-explicit

uv pip compile requirements.in --prerelease allow

Environment: UV_PRERELEASE

--fork-strategy

string

Version selection strategy: requires-python or fewest.Default: requires-pythonEnvironment: UV_FORK_STRATEGY

--no-deps

Only add explicitly listed packages, not their dependencies.

uv pip compile requirements.in --no-deps

Output Formatting

--no-strip-extras

Include extras in output file.By default, uv strips extras as dependencies are already included.

uv pip compile requirements.in --no-strip-extras

--no-strip-markers

Include environment markers in output.

uv pip compile requirements.in --no-strip-markers

--no-annotate

Exclude comments indicating package sources.

uv pip compile requirements.in --no-annotate

--annotation-style

string

Annotation comment style: line, split.Default: split

uv pip compile requirements.in --annotation-style line

--no-header

Exclude the header comment from output.

uv pip compile requirements.in --no-header

--custom-compile-command

string

Custom command for header (for build script wrappers).

uv pip compile requirements.in --custom-compile-command "make requirements"

Environment: UV_CUSTOM_COMPILE_COMMAND

--emit-index-url

Include --index-url and --extra-index-url in output.

uv pip compile requirements.in --emit-index-url

--emit-find-links

Include --find-links in output.

uv pip compile requirements.in --emit-find-links

--emit-build-options

Include --no-binary and --only-binary in output.

uv pip compile requirements.in --emit-build-options

--emit-index-annotation

Include index source in comments.

uv pip compile requirements.in --emit-index-annotation

--no-emit-package

package[]

Omit specific packages from output (but include dependencies).Equivalent to pip-compile’s --unsafe-package.

uv pip compile requirements.in --no-emit-package setuptools

Hash Generation

--generate-hashes

Include distribution hashes in output.

uv pip compile requirements.in --generate-hashes

Python Environment

-p, --python

string

Python interpreter for building source distributions.Also determines minimum Python version unless --python-version is provided.

uv pip compile requirements.in --python 3.11
uv pip compile requirements.in --python /path/to/python

Environment: UV_PYTHON

--system

Use system Python instead of virtual environment.

uv pip compile requirements.in --system

Environment: UV_SYSTEM_PYTHON

--python-version

version

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

uv pip compile requirements.in --python-version 3.8

--python-platform

triple

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

uv pip compile requirements.in --python-platform x86_64-unknown-linux-gnu

--universal

Create a universal resolution for all platforms and Python versions.The specified --python-version is treated as a lower bound.Implies --no-strip-markers.

uv pip compile requirements.in --universal --python-version 3.8

Build Options

--no-build

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

uv pip compile requirements.in --no-build

--no-binary

package[]

Build specific packages from source.

uv pip compile requirements.in --no-binary numpy
uv pip compile requirements.in --no-binary :all:

--only-binary

package[]

Only use pre-built wheels for specific packages.

uv pip compile requirements.in --only-binary pillow
uv pip compile requirements.in --only-binary :all:

-C, --config-setting

key=value[]

Pass settings to the PEP 517 build backend.

uv pip compile requirements.in --config-setting="--build-option=--debug"

--config-settings-package

package:key=value[]

Pass package-specific settings to build backends.

uv pip compile requirements.in --config-settings-package="numpy:--with-lapack"

--no-build-isolation

Disable build isolation. Assumes build dependencies are already installed.

uv pip compile requirements.in --no-build-isolation

Environment: UV_NO_BUILD_ISOLATION

--no-build-isolation-package

package[]

Disable build isolation for specific packages.

uv pip compile requirements.in --no-build-isolation-package numpy

Index Options

--index

url[]

Package indexes to use (in addition to default).

uv pip compile requirements.in --index https://pypi.org/simple

Environment: UV_INDEX

--default-index

url

Default package index (replaces PyPI).

uv pip compile requirements.in --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 compile requirements.in --find-links ./wheels

Environment: UV_FIND_LINKS

--no-index

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

uv pip compile requirements.in --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

Version Constraints

--exclude-newer

date

Exclude packages uploaded after the specified date.

uv pip compile requirements.in --exclude-newer 2024-01-01
uv pip compile requirements.in --exclude-newer "7 days"

Environment: UV_EXCLUDE_NEWER

--exclude-newer-package

package=date[]

Exclude specific packages uploaded after dates.

uv pip compile requirements.in --exclude-newer-package "numpy=2024-01-01"

--link-mode

string

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

uv Extensions

--torch-backend

string

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

Preview feature. May change in future releases.

uv pip compile requirements.in --torch-backend cu126

Environment: UV_TORCH_BACKEND

--no-sources

Ignore tool.uv.sources in pyproject.toml.Environment: UV_NO_SOURCES

--no-sources-package

package[]

Ignore sources for specific packages.Environment: UV_NO_SOURCES_PACKAGE

Cache Options

--refresh

Refresh all cached data.

uv pip compile requirements.in --refresh

--refresh-package

package[]

Refresh cached data for specific packages.

uv pip compile requirements.in --refresh-package numpy

Examples

Basic Compilation

# Compile requirements.in
uv pip compile requirements.in -o requirements.txt

# Compile pyproject.toml
uv pip compile pyproject.toml -o requirements.txt

# Multiple input files
uv pip compile requirements.in dev-requirements.in -o requirements.txt

With Extras

# Compile with specific extras
uv pip compile pyproject.toml --extra dev -o requirements.txt

# Compile with all extras
uv pip compile pyproject.toml --all-extras -o requirements.txt

# Multiple extras
uv pip compile pyproject.toml --extra dev --extra test -o requirements.txt

Upgrading Dependencies

# Upgrade all packages
uv pip compile requirements.in --upgrade -o requirements.txt

# Upgrade specific packages
uv pip compile requirements.in --upgrade-package requests -o requirements.txt

# Upgrade multiple packages
uv pip compile requirements.in -P requests -P flask -o requirements.txt

Universal Resolution

# Create universal resolution for Python 3.8+
uv pip compile requirements.in --universal --python-version 3.8 -o requirements.txt

# Universal resolution keeps markers
uv pip compile requirements.in --universal -o requirements.txt

With Constraints

# Apply version constraints
uv pip compile requirements.in -c constraints.txt -o requirements.txt

# Override specific versions
uv pip compile requirements.in --override overrides.txt -o requirements.txt

Hash Generation

# Generate hashes for security
uv pip compile requirements.in --generate-hashes -o requirements.txt

Custom Output Format

# Output as pylock.toml
uv pip compile requirements.in --format pylock -o pylock.toml

# Without annotations
uv pip compile requirements.in --no-annotate -o requirements.txt

# With minimal output
uv pip compile requirements.in --no-header --no-annotate -o requirements.txt

Custom Indexes

# Use private index
uv pip compile requirements.in --index https://private.pypi.org/simple -o requirements.txt

# Include index URLs in output
uv pip compile requirements.in --emit-index-url -o requirements.txt

Cross-Platform

# Compile for specific Python version
uv pip compile requirements.in --python-version 3.8 -o requirements.txt

# Compile for specific platform
uv pip compile requirements.in --python-platform x86_64-unknown-linux-gnu -o requirements.txt

Build Options

# Don't build source distributions
uv pip compile requirements.in --no-build -o requirements.txt

# Build specific package from source
uv pip compile requirements.in --no-binary numpy -o requirements.txt

pip-tools Compatibility

uv pip compile is designed to be compatible with pip-compile from pip-tools:

# pip-compile command
pip-compile requirements.in

# Equivalent uv command
uv pip compile requirements.in -o requirements.txt

Differences from pip-compile

Performance: uv is significantly faster (10-100x)
Output file: uv requires explicit -o flag; pip-compile infers it
Markers: uv strips markers by default; use --no-strip-markers for pip-compile behavior
Extras: uv strips extras by default; use --no-strip-extras for pip-compile behavior
Resolution: uv uses a more sophisticated resolver

Migration from pip-compile

# pip-compile (infers output)
pip-compile requirements.in

# uv equivalent (explicit output)
uv pip compile requirements.in -o requirements.txt

# With markers preserved
uv pip compile requirements.in --no-strip-markers -o requirements.txt

Output Format

The default output is a requirements.txt file:

# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in -o requirements.txt
certifi==2024.2.2
    # via requests
charset-normalizer==3.3.2
    # via requests
idna==3.6
    # via requests
requests==2.31.0
    # via -r requirements.in
urllib3==2.2.1
    # via requests

With --format pylock, output is in PEP 751 format:

version = 1

[[package]]
name = "requests"
version = "2.31.0"
source = { url = "https://pypi.org/simple" }
# ...

uv pip install - Install packages
uv pip sync - Sync environment with lockfile
uv lock - Lock project dependencies

​Usage

​Arguments

​Input Sources

​Output Options

​Constraints and Overrides

​Optional Dependencies

​Resolver Options

​Output Formatting

​Hash Generation

​Python Environment

​Build Options

​Index Options

​Version Constraints

​uv Extensions

​Cache Options

​Examples

​Basic Compilation

​With Extras

​Upgrading Dependencies

​Universal Resolution

​With Constraints

​Hash Generation

​Custom Output Format

​Custom Indexes

​Cross-Platform

​Build Options

​pip-tools Compatibility

​Differences from pip-compile

​Migration from pip-compile

​Output Format

​Related Commands

Usage

Arguments

Input Sources

Output Options

Constraints and Overrides

Optional Dependencies

Resolver Options

Output Formatting

Hash Generation

Python Environment

Build Options

Index Options

Version Constraints

uv Extensions

Cache Options

Examples

Basic Compilation

With Extras

Upgrading Dependencies

Universal Resolution

With Constraints

Hash Generation

Custom Output Format

Custom Indexes

Cross-Platform

Build Options

pip-tools Compatibility

Differences from pip-compile

Migration from pip-compile

Output Format

Related Commands