> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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

<ParamField body="package" type="string[]">
  Packages to install. Can be package names, URLs, file paths, or version specifications.

  ```bash theme={null}
  uv pip install requests "flask>=2.0" https://example.com/package.whl
  ```
</ParamField>

<ParamField body="-r, --requirements" type="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.

  ```bash theme={null}
  uv pip install -r requirements.txt -r dev-requirements.txt
  ```
</ParamField>

<ParamField body="-e, --editable" type="string[]">
  Install a package in editable mode from a local path.

  ```bash theme={null}
  uv pip install -e ./my-package
  uv pip install -e git+https://github.com/user/repo.git
  ```
</ParamField>

### Constraints and Overrides

<ParamField body="-c, --constraint" type="path[]">
  Constrain package versions without requiring installation.

  ```bash theme={null}
  uv pip install requests -c constraints.txt
  ```

  Environment: `UV_CONSTRAINT`
</ParamField>

<ParamField body="--override" type="path[]">
  Override package versions, ignoring dependencies.

  ```bash theme={null}
  uv pip install requests --override overrides.txt
  ```

  Environment: `UV_OVERRIDE`
</ParamField>

<ParamField body="--exclude" type="path[]">
  Exclude packages from resolution.

  ```bash theme={null}
  uv pip install mypackage --exclude excludes.txt
  ```

  Environment: `UV_EXCLUDE`
</ParamField>

<ParamField body="-B, --build-constraint" type="path[]">
  Constrain build dependencies when building from source.

  ```bash theme={null}
  uv pip install mypackage --build-constraint build-constraints.txt
  ```

  Environment: `UV_BUILD_CONSTRAINT`
</ParamField>

### Optional Dependencies

<ParamField body="--extra" type="string[]">
  Include optional dependencies (extras).

  ```bash theme={null}
  uv pip install -r pyproject.toml --extra dev --extra test
  ```
</ParamField>

<ParamField body="--all-extras">
  Include all optional dependencies.

  ```bash theme={null}
  uv pip install -r pyproject.toml --all-extras
  ```
</ParamField>

<ParamField body="--group" type="string[]">
  Install dependency groups from `pylock.toml` or `pyproject.toml`.

  ```bash theme={null}
  uv pip install --group dev --group test
  ```
</ParamField>

### Python Environment

<ParamField body="-p, --python" type="string">
  Python interpreter to use for installation.

  ```bash theme={null}
  uv pip install requests --python 3.11
  uv pip install requests --python /path/to/python
  ```

  Environment: `UV_PYTHON`
</ParamField>

<ParamField body="--system">
  Install into system Python instead of a virtual environment.

  <Warning>
    Use with caution in CI environments only. Can modify system Python installation.
  </Warning>

  ```bash theme={null}
  uv pip install requests --system
  ```

  Environment: `UV_SYSTEM_PYTHON`
</ParamField>

<ParamField body="--break-system-packages">
  Allow installation into externally-managed Python environments.

  <Warning>
    Intended for CI environments. Use with caution.
  </Warning>

  Environment: `UV_BREAK_SYSTEM_PACKAGES`
</ParamField>

<ParamField body="-t, --target" type="path">
  Install packages into the specified directory.

  ```bash theme={null}
  uv pip install requests --target ./libs
  ```
</ParamField>

<ParamField body="--prefix" type="path">
  Install packages into lib, bin folders under the specified directory.

  ```bash theme={null}
  uv pip install requests --prefix /opt/myapp
  ```
</ParamField>

### Resolver Options

<ParamField body="-U, --upgrade">
  Upgrade all packages to the latest compatible versions.

  ```bash theme={null}
  uv pip install requests --upgrade
  ```
</ParamField>

<ParamField body="-P, --upgrade-package" type="requirement[]">
  Upgrade specific packages while keeping others pinned.

  ```bash theme={null}
  uv pip install -r requirements.txt --upgrade-package requests --upgrade-package flask
  ```
</ParamField>

<ParamField body="--resolution" type="string">
  Resolution strategy: `highest`, `lowest`, or `lowest-direct`.

  Default: `highest`

  ```bash theme={null}
  uv pip install mypackage --resolution lowest
  ```

  Environment: `UV_RESOLUTION`
</ParamField>

<ParamField body="--prerelease" type="string">
  Pre-release handling: `disallow`, `allow`, `if-necessary`, `explicit`, or `if-necessary-or-explicit`.

  Default: `if-necessary-or-explicit`

  ```bash theme={null}
  uv pip install mypackage --prerelease allow
  ```

  Environment: `UV_PRERELEASE`
</ParamField>

<ParamField body="--fork-strategy" type="string">
  Version selection strategy: `requires-python` or `fewest`.

  Default: `requires-python`

  Environment: `UV_FORK_STRATEGY`
</ParamField>

<ParamField body="--no-deps">
  Don't install package dependencies.

  ```bash theme={null}
  uv pip install mypackage --no-deps
  ```
</ParamField>

### Build Options

<ParamField body="--no-build">
  Don't build source distributions. Only use pre-built wheels.

  Alias for `--only-binary :all:`

  ```bash theme={null}
  uv pip install mypackage --no-build
  ```
</ParamField>

<ParamField body="--no-binary" type="package[]">
  Build specific packages from source instead of using wheels.

  ```bash theme={null}
  uv pip install mypackage --no-binary numpy
  uv pip install mypackage --no-binary :all:
  ```
</ParamField>

<ParamField body="--only-binary" type="package[]">
  Only use pre-built wheels for specific packages.

  ```bash theme={null}
  uv pip install mypackage --only-binary pillow
  uv pip install mypackage --only-binary :all:
  ```
</ParamField>

<ParamField body="-C, --config-setting" type="key=value[]">
  Pass settings to the PEP 517 build backend.

  ```bash theme={null}
  uv pip install mypackage --config-setting="--build-option=--debug"
  ```
</ParamField>

<ParamField body="--config-settings-package" type="package:key=value[]">
  Pass package-specific settings to build backends.

  ```bash theme={null}
  uv pip install mypackage --config-settings-package="numpy:--with-lapack"
  ```
</ParamField>

<ParamField body="--no-build-isolation">
  Disable build isolation. Assumes build dependencies are already installed.

  ```bash theme={null}
  uv pip install mypackage --no-build-isolation
  ```

  Environment: `UV_NO_BUILD_ISOLATION`
</ParamField>

<ParamField body="--no-build-isolation-package" type="package[]">
  Disable build isolation for specific packages.

  ```bash theme={null}
  uv pip install mypackage --no-build-isolation-package numpy
  ```
</ParamField>

### Index Options

<ParamField body="--index" type="url[]">
  Package indexes to use (in addition to default).

  ```bash theme={null}
  uv pip install mypackage --index https://pypi.org/simple
  ```

  Environment: `UV_INDEX`
</ParamField>

<ParamField body="--default-index" type="url">
  Default package index (replaces PyPI).

  ```bash theme={null}
  uv pip install mypackage --default-index https://private.pypi.org/simple
  ```

  Environment: `UV_DEFAULT_INDEX`
</ParamField>

<ParamField body="-i, --index-url" type="url">
  Deprecated: Use `--default-index` instead.

  Environment: `UV_INDEX_URL`
</ParamField>

<ParamField body="--extra-index-url" type="url[]">
  Deprecated: Use `--index` instead.

  Environment: `UV_EXTRA_INDEX_URL`
</ParamField>

<ParamField body="-f, --find-links" type="path|url[]">
  Additional locations to search for packages.

  ```bash theme={null}
  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`
</ParamField>

<ParamField body="--no-index">
  Ignore package indexes, only use `--find-links`.

  ```bash theme={null}
  uv pip install mypackage --no-index --find-links ./wheels
  ```
</ParamField>

<ParamField body="--index-strategy" type="string">
  Index selection strategy: `first-index`, `unsafe-first-match`, or `unsafe-best-match`.

  Default: `first-index`

  Environment: `UV_INDEX_STRATEGY`
</ParamField>

<ParamField body="--keyring-provider" type="string">
  Keyring provider for authentication: `disabled`, `subprocess`.

  Default: `disabled`

  Environment: `UV_KEYRING_PROVIDER`
</ParamField>

### Hash Verification

<ParamField body="--require-hashes">
  Require hash verification for all packages.

  ```bash theme={null}
  uv pip install -r requirements.txt --require-hashes
  ```

  Environment: `UV_REQUIRE_HASHES`
</ParamField>

<ParamField body="--no-verify-hashes">
  Disable hash verification.

  Environment: `UV_NO_VERIFY_HASHES`
</ParamField>

### Version Constraints

<ParamField body="--python-version" type="version">
  Minimum Python version to support (e.g., `3.8` or `3.8.17`).

  ```bash theme={null}
  uv pip install mypackage --python-version 3.8
  ```
</ParamField>

<ParamField body="--python-platform" type="triple">
  Target platform triple (e.g., `x86_64-unknown-linux-gnu`).

  <Warning>
    Advanced use case. May install incompatible packages.
  </Warning>

  ```bash theme={null}
  uv pip install mypackage --python-platform x86_64-unknown-linux-gnu
  ```
</ParamField>

### Installation Behavior

<ParamField body="--reinstall">
  Reinstall all packages, ignoring existing installations.

  ```bash theme={null}
  uv pip install mypackage --reinstall
  ```
</ParamField>

<ParamField body="--reinstall-package" type="package[]">
  Reinstall specific packages.

  ```bash theme={null}
  uv pip install mypackage --reinstall-package numpy
  ```
</ParamField>

<ParamField body="--exact">
  Remove extraneous packages not in requirements.

  ```bash theme={null}
  uv pip install -r requirements.txt --exact
  ```
</ParamField>

<ParamField body="--strict">
  Validate environment after installation.

  ```bash theme={null}
  uv pip install mypackage --strict
  ```
</ParamField>

<ParamField body="--dry-run">
  Show installation plan without installing.

  ```bash theme={null}
  uv pip install mypackage --dry-run
  ```
</ParamField>

<ParamField body="--exclude-newer" type="date">
  Exclude packages uploaded after the specified date.

  ```bash theme={null}
  uv pip install mypackage --exclude-newer 2024-01-01
  uv pip install mypackage --exclude-newer "7 days"
  ```

  Environment: `UV_EXCLUDE_NEWER`
</ParamField>

<ParamField body="--exclude-newer-package" type="package=date[]">
  Exclude specific packages uploaded after dates.

  ```bash theme={null}
  uv pip install mypackage --exclude-newer-package "numpy=2024-01-01"
  ```
</ParamField>

<ParamField body="--link-mode" type="string">
  Link mode for installations: `clone`, `copy`, `hardlink`, `symlink`.

  Default: `clone` on macOS/Linux, `hardlink` on Windows

  Environment: `UV_LINK_MODE`
</ParamField>

<ParamField body="--compile-bytecode">
  Compile Python files to bytecode after installation.

  ```bash theme={null}
  uv pip install mypackage --compile-bytecode
  ```

  Environment: `UV_COMPILE_BYTECODE`
</ParamField>

### uv Extensions

<ParamField body="--torch-backend" type="string">
  PyTorch backend: `cpu`, `cu126`, `cu124`, `cu121`, `cu118`, or `auto`.

  <Info>
    Preview feature. May change in future releases.
  </Info>

  ```bash theme={null}
  uv pip install torch --torch-backend cu126
  ```

  Environment: `UV_TORCH_BACKEND`
</ParamField>

<ParamField body="--no-sources">
  Ignore `tool.uv.sources` in `pyproject.toml`.

  Environment: `UV_NO_SOURCES`
</ParamField>

<ParamField body="--no-sources-package" type="package[]">
  Ignore sources for specific packages.

  Environment: `UV_NO_SOURCES_PACKAGE`
</ParamField>

### Cache Options

<ParamField body="--refresh">
  Refresh all cached data.

  ```bash theme={null}
  uv pip install mypackage --refresh
  ```
</ParamField>

<ParamField body="--refresh-package" type="package[]">
  Refresh cached data for specific packages.

  ```bash theme={null}
  uv pip install mypackage --refresh-package numpy
  ```
</ParamField>

## Examples

### Basic Installation

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Upgrade all packages
uv pip install -r requirements.txt --upgrade

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

### Custom Index

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Require hashes for all packages
uv pip install -r requirements.txt --require-hashes
```

### Dry Run

```bash theme={null}
# 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:

```bash theme={null}
# 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`](/cli/pip-sync) - Sync environment with a lockfile
* [`uv pip uninstall`](/cli/pip-uninstall) - Uninstall packages
* [`uv pip list`](/cli/pip-list) - List installed packages
* [`uv pip freeze`](/cli/pip-freeze) - Output installed packages