uv pip compile

Compile a requirements file to a locked format.

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-python

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

Environment: UV_INDEX_STRATEGY

--keyring-provider · string

Keyring provider for authentication: disabled, subprocess.

Default: disabled

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

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

1. Performance: uv is significantly faster (10-100x)
2. Output file: uv requires explicit -o flag; pip-compile infers it
3. Markers: uv strips markers by default; use --no-strip-markers for pip-compile behavior
4. Extras: uv strips extras by default; use --no-strip-extras for pip-compile behavior
5. 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" }
# ...

Related Commands

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