uv pip install

Install packages into a Python environment.

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

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

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 Windows

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

1. Performance: uv is significantly faster due to Rust implementation and parallel downloads
2. Default behavior: uv requires a virtual environment by default (use --system to override)
3. Resolution: uv uses a modern dependency resolver by default
4. Caching: uv has a more sophisticated caching strategy
5. 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

Related Commands

• 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