uv pip install

uv pip install installs packages into the active Python environment. It is compatible with pip install but offers significantly faster performance.

Usage

# Install a package
uv pip install requests

# Install multiple packages
uv pip install requests flask numpy

# Install from requirements file
uv pip install -r requirements.txt

# Install with extras
uv pip install "fastapi[all]"

# Install in editable mode
uv pip install -e .

# Install specific version
uv pip install "django>=4.0,<5.0"

Arguments

Package Sources

package

string[]

Packages to install. Can be package names, URLs, file paths, or version specifications.

uv pip install requests "flask>=2.0" https://example.com/package.whl

-r, --requirements

path[]

Install packages from requirements files.Supports:

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

Use - to read from stdin.

uv pip install -r requirements.txt -r dev-requirements.txt

-e, --editable

string[]

Install a package in editable mode from a local path.

uv pip install -e ./my-package
uv pip install -e git+https://github.com/user/repo.git

Constraints and Overrides

-c, --constraint

path[]

Constrain package versions without requiring installation.

uv pip install requests -c constraints.txt

Environment: UV_CONSTRAINT

--override

path[]

Override package versions, ignoring dependencies.

uv pip install requests --override overrides.txt

Environment: UV_OVERRIDE

--exclude

path[]

Exclude packages from resolution.

uv pip install mypackage --exclude excludes.txt

Environment: UV_EXCLUDE

-B, --build-constraint

path[]

Constrain build dependencies when building from source.

uv pip install mypackage --build-constraint build-constraints.txt

Environment: UV_BUILD_CONSTRAINT

Optional Dependencies

--extra

string[]

Include optional dependencies (extras).

uv pip install -r pyproject.toml --extra dev --extra test

--all-extras

Include all optional dependencies.

uv pip install -r pyproject.toml --all-extras

--group

string[]

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

uv pip install --group dev --group test

Python Environment

-p, --python

string

Python interpreter to use for installation.

uv pip install requests --python 3.11
uv pip install requests --python /path/to/python

Environment: UV_PYTHON

--system

Install into system Python instead of a virtual environment.

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

uv pip install requests --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

Install packages into the specified directory.

uv pip install requests --target ./libs

--prefix

path

Install packages into lib, bin folders under the specified directory.

uv pip install requests --prefix /opt/myapp

Resolver Options

-U, --upgrade

Upgrade all packages to the latest compatible versions.

uv pip install requests --upgrade

-P, --upgrade-package

requirement[]

Upgrade specific packages while keeping others pinned.

uv pip install -r requirements.txt --upgrade-package requests --upgrade-package flask

--resolution

string

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

uv pip install mypackage --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 install mypackage --prerelease allow

Environment: UV_PRERELEASE

--fork-strategy

string

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

--no-deps

Don’t install package dependencies.

uv pip install mypackage --no-deps

Build Options

--no-build

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

uv pip install mypackage --no-build

--no-binary

package[]

Build specific packages from source instead of using wheels.

uv pip install mypackage --no-binary numpy
uv pip install mypackage --no-binary :all:

--only-binary

package[]

Only use pre-built wheels for specific packages.

uv pip install mypackage --only-binary pillow
uv pip install mypackage --only-binary :all:

-C, --config-setting

key=value[]

Pass settings to the PEP 517 build backend.

uv pip install mypackage --config-setting="--build-option=--debug"

--config-settings-package

package:key=value[]

Pass package-specific settings to build backends.

uv pip install mypackage --config-settings-package="numpy:--with-lapack"

--no-build-isolation

Disable build isolation. Assumes build dependencies are already installed.

uv pip install mypackage --no-build-isolation

Environment: UV_NO_BUILD_ISOLATION

--no-build-isolation-package

package[]

Disable build isolation for specific packages.

uv pip install mypackage --no-build-isolation-package numpy

Index Options

--index

url[]

Package indexes to use (in addition to default).

uv pip install mypackage --index https://pypi.org/simple

Environment: UV_INDEX

--default-index

url

Default package index (replaces PyPI).

uv pip install mypackage --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 install mypackage --find-links ./wheels
uv pip install mypackage --find-links https://download.pytorch.org/whl/torch_stable.html

Environment: UV_FIND_LINKS

--no-index

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

uv pip install mypackage --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.

uv pip install -r 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 install mypackage --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 install mypackage --python-platform x86_64-unknown-linux-gnu

Installation Behavior

--reinstall

Reinstall all packages, ignoring existing installations.

uv pip install mypackage --reinstall

--reinstall-package

package[]

Reinstall specific packages.

uv pip install mypackage --reinstall-package numpy

--exact

Remove extraneous packages not in requirements.

uv pip install -r requirements.txt --exact

--strict

Validate environment after installation.

uv pip install mypackage --strict

--dry-run

Show installation plan without installing.

uv pip install mypackage --dry-run

--exclude-newer

date

Exclude packages uploaded after the specified date.

uv pip install mypackage --exclude-newer 2024-01-01
uv pip install mypackage --exclude-newer "7 days"

Environment: UV_EXCLUDE_NEWER

--exclude-newer-package

package=date[]

Exclude specific packages uploaded after dates.

uv pip install mypackage --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 install mypackage --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 install torch --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 install mypackage --refresh

--refresh-package

package[]

Refresh cached data for specific packages.

uv pip install mypackage --refresh-package numpy

Examples

Basic Installation

# Install a single package
uv pip install requests

# Install multiple packages
uv pip install requests flask sqlalchemy

# Install with version constraints
uv pip install "django>=4.0,<5.0" "requests~=2.31.0"

From Requirements Files

# Install from requirements.txt
uv pip install -r requirements.txt

# Install from multiple files
uv pip install -r requirements.txt -r dev-requirements.txt

# Install from pyproject.toml
uv pip install -r pyproject.toml

# Install from stdin
echo "requests" | uv pip install -r -

Editable Installations

# Install local package in editable mode
uv pip install -e .
uv pip install -e ./my-package

# Install from Git in editable mode
uv pip install -e git+https://github.com/user/repo.git

With Extras

# Install with a single extra
uv pip install "fastapi[all]"

# Install with multiple extras
uv pip install "django[argon2,bcrypt]"

# Install project with all extras
uv pip install -r pyproject.toml --all-extras

Upgrade Packages

# Upgrade all packages
uv pip install -r requirements.txt --upgrade

# Upgrade specific packages
uv pip install -r requirements.txt --upgrade-package requests

Custom Index

# Use private index
uv pip install mypackage --index https://private.pypi.org/simple

# Replace default index
uv pip install mypackage --default-index https://private.pypi.org/simple

# Multiple indexes (earlier takes priority)
uv pip install mypackage --index https://pypi.org/simple --index https://private.pypi.org/simple

Local Wheels

# Install from local directory
uv pip install mypackage --find-links ./wheels --no-index

# Prefer local wheels
uv pip install mypackage --find-links ./wheels

Build from Source

# Build specific package from source
uv pip install mypackage --no-binary mypackage

# Build all packages from source
uv pip install mypackage --no-binary :all:

# Only use pre-built wheels
uv pip install mypackage --only-binary :all:

Cross-Platform

# Install for different Python version
uv pip install mypackage --python-version 3.8

# Install for different platform
uv pip install mypackage --python-platform x86_64-unknown-linux-gnu

Hash Verification

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

Dry Run

# Preview installation plan
uv pip install mypackage --dry-run

pip Compatibility

uv pip install is designed to be compatible with pip install. Most pip commands work with uv:

# pip command
pip install requests

# Equivalent uv command
uv pip install requests

Differences from pip

Performance: uv is significantly faster due to Rust implementation and parallel downloads
Default behavior: uv requires a virtual environment by default (use --system to override)
Resolution: uv uses a modern dependency resolver by default
Caching: uv has a more sophisticated caching strategy
Index URLs: Deprecated --index-url in favor of --default-index

Unsupported pip Options

Most pip options are supported. Notable exceptions include:

--user: Use virtual environments or --system instead
Some legacy pip behaviors

uv pip sync - Sync environment with a lockfile
uv pip uninstall - Uninstall packages
uv pip list - List installed packages
uv pip freeze - Output installed packages

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

uv pip install

Usage

Arguments

Package Sources

Constraints and Overrides

Optional Dependencies

Python Environment

Resolver Options

Build Options

Index Options

Hash Verification

Version Constraints

Installation Behavior

uv Extensions

Cache Options

Examples

Basic Installation

From Requirements Files

Editable Installations

With Extras

Upgrade Packages

Custom Index

Local Wheels

Build from Source

Cross-Platform

Hash Verification

Dry Run

pip Compatibility

Differences from pip

Unsupported pip Options

Build docs developers (and LLMs) love

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​Usage

​Arguments

​Package Sources

​Constraints and Overrides

​Optional Dependencies

​Python Environment

​Resolver Options

​Build Options

​Index Options

​Hash Verification

​Version Constraints

​Installation Behavior

​uv Extensions

​Cache Options

​Examples

​Basic Installation

​From Requirements Files

​Editable Installations

​With Extras

​Upgrade Packages

​Custom Index

​Local Wheels

​Build from Source

​Cross-Platform

​Hash Verification

​Dry Run

​pip Compatibility

​Differences from pip

​Unsupported pip Options

​Related Commands

Build docs developers (and LLMs) love

Usage

Arguments

Package Sources

Constraints and Overrides

Optional Dependencies

Python Environment

Resolver Options

Build Options

Index Options

Hash Verification

Version Constraints

Installation Behavior

uv Extensions

Cache Options

Examples

Basic Installation

From Requirements Files

Editable Installations

With Extras

Upgrade Packages

Custom Index

Local Wheels

Build from Source

Cross-Platform

Hash Verification

Dry Run

pip Compatibility

Differences from pip

Unsupported pip Options

Related Commands