> ## 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.

# Using the pip Interface

> Drop-in replacement for pip, pip-tools, and virtualenv commands

## Overview

uv provides a drop-in replacement for common `pip`, `pip-tools`, and `virtualenv` commands. These commands work directly with virtual environments, offering the speed and functionality of uv to power users and projects not ready to transition from pip.

<Note>
  The `uv pip` interface operates at a lower level than uv's primary project interface. For new projects, consider using [projects](./projects.mdx) instead.
</Note>

<Warning>
  These commands don't *exactly* match the tools they're based on. The further you stray from common workflows, the more likely you are to encounter differences. See the [pip compatibility guide](../pip/compatibility.md) for details.
</Warning>

<Info>
  uv doesn't rely on or invoke pip. The pip interface is named to highlight its purpose: providing low-level commands matching pip's interface, separate from uv's higher-level abstractions.
</Info>

## Creating and using environments

### Creating virtual environments

Create a virtual environment like `python -m venv`:

```bash theme={null}
uv venv
```

This creates a `.venv` directory in the current location.

<CodeGroup>
  ```bash Custom name theme={null}
  uv venv myenv
  ```

  ```bash Specific Python version theme={null}
  uv venv --python 3.11
  ```

  ```bash Python from path theme={null}
  uv venv --python /usr/bin/python3.10
  ```
</CodeGroup>

### Activating environments

After creating, activate the environment:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  source .venv/bin/activate
  ```

  ```powershell Windows (PowerShell) theme={null}
  .venv\Scripts\activate
  ```

  ```cmd Windows (Command Prompt) theme={null}
  .venv\Scripts\activate.bat
  ```
</CodeGroup>

See [creating environments](../pip/environments.md) for more details.

## Installing and managing packages

### Installing packages

<Steps>
  <Step title="Install a single package">
    ```bash theme={null}
    uv pip install flask
    ```
  </Step>

  <Step title="Install with extras">
    ```bash theme={null}
    uv pip install "flask[dotenv]"
    ```
  </Step>

  <Step title="Install multiple packages">
    ```bash theme={null}
    uv pip install flask ruff
    ```
  </Step>

  <Step title="Install with constraints">
    ```bash theme={null}
    uv pip install 'ruff>=0.2.0'
    ```
  </Step>
</Steps>

### Installing from different sources

<CodeGroup>
  ```bash Specific version theme={null}
  uv pip install 'ruff==0.3.0'
  ```

  ```bash Local path theme={null}
  uv pip install "ruff @ ./projects/ruff"
  ```

  ```bash GitHub theme={null}
  uv pip install "git+https://github.com/astral-sh/ruff"
  ```

  ```bash GitHub with ref theme={null}
  uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"
  ```
</CodeGroup>

See [Git authentication](../concepts/authentication/git.md) for private repositories.

### Editable packages

Install packages in editable mode:

<CodeGroup>
  ```bash Current directory theme={null}
  uv pip install -e .
  ```

  ```bash Other directory theme={null}
  uv pip install -e "ruff @ ./project/ruff"
  ```
</CodeGroup>

Changes to source code are immediately active.

### Installing from files

Install from various file formats:

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

  ```bash pyproject.toml theme={null}
  uv pip install -r pyproject.toml
  ```

  ```bash With extras theme={null}
  uv pip install -r pyproject.toml --extra foo
  ```

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

### Installing dependency groups

Install groups from `pyproject.toml`:

<CodeGroup>
  ```bash Single group theme={null}
  uv pip install --group foo
  ```

  ```bash Multiple groups theme={null}
  uv pip install --group foo --group bar
  ```

  ```bash From specific path theme={null}
  uv pip install --project some/path/ --group foo
  ```

  ```bash With explicit path theme={null}
  uv pip install --group some/path/pyproject.toml:foo
  ```
</CodeGroup>

<Note>
  `--group` flags don't apply to other sources like `-r`. For example, `uv pip install -r some/path/pyproject.toml --group foo` sources `foo` from `./pyproject.toml`, not `some/path/pyproject.toml`.
</Note>

### Uninstalling packages

<CodeGroup>
  ```bash Single package theme={null}
  uv pip uninstall flask
  ```

  ```bash Multiple packages theme={null}
  uv pip uninstall flask ruff
  ```
</CodeGroup>

See [managing packages](../pip/packages.md) for more details.

## Locking and syncing environments

### Locking requirements

Generate a locked `requirements.txt`:

<CodeGroup>
  ```bash From pyproject.toml theme={null}
  uv pip compile pyproject.toml -o requirements.txt
  ```

  ```bash From requirements.in theme={null}
  uv pip compile requirements.in -o requirements.txt
  ```

  ```bash Multiple sources theme={null}
  uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt
  ```

  ```bash From stdin theme={null}
  echo "ruff" | uv pip compile -
  ```
</CodeGroup>

<Note>
  By default, `uv pip compile` prints output to stdout. Use `-o` / `--output-file` to write to a file.
</Note>

### Compiling with extras

<CodeGroup>
  ```bash Single extra theme={null}
  uv pip compile pyproject.toml --extra foo
  ```

  ```bash All extras theme={null}
  uv pip compile pyproject.toml --all-extras
  ```

  ```bash Dependency groups theme={null}
  uv pip compile --group foo
  ```
</CodeGroup>

<Info>
  A `--group` flag was added to `uv pip compile`, though [pip-tools is considering it](https://github.com/jazzband/pip-tools/issues/2062). We'll support whatever syntax they adopt.
</Info>

### Upgrading requirements

uv respects existing pinned versions in output files:

```bash theme={null}
echo "ruff==0.3.0" > requirements.txt
echo "ruff" | uv pip compile - -o requirements.txt
# ruff==0.3.0  (unchanged)
```

Upgrade specific packages:

```bash theme={null}
uv pip compile requirements.in -o requirements.txt --upgrade-package ruff
```

Or upgrade everything:

```bash theme={null}
uv pip compile requirements.in -o requirements.txt --upgrade
```

### Syncing environments

Sync environment to exactly match a lockfile:

<CodeGroup>
  ```bash requirements.txt theme={null}
  uv pip sync requirements.txt
  ```

  ```bash pylock.toml (PEP 751) theme={null}
  uv pip sync pylock.toml
  ```
</CodeGroup>

<Warning>
  `uv pip install` keeps existing packages that don't conflict. `uv pip sync` removes any packages not in the lockfile, ensuring exact reproducibility.
</Warning>

See [locking environments](../pip/compile.md) for more details.

## Inspecting environments and packages

### List installed packages

<CodeGroup>
  ```bash All packages theme={null}
  uv pip list
  ```

  ```bash With versions theme={null}
  uv pip freeze
  ```

  ```bash Specific package theme={null}
  uv pip show flask
  ```
</CodeGroup>

### Check package information

```bash theme={null}
uv pip show httpx
# Name: httpx
# Version: 0.24.1
# Location: /path/to/site-packages
# Requires: certifi, httpcore, idna, sniffio
# Required-by: 
```

See [inspecting environments](../pip/inspection.md) for more details.

## Working with constraints and overrides

### Adding constraints

Constraint files control versions without triggering installation:

```python constraints.txt theme={null}
pydantic<2.0
```

```bash theme={null}
uv pip compile requirements.in --constraint constraints.txt
```

uv also reads `constraint-dependencies` from workspace root `pyproject.toml`.

### Build constraints

Constrain build-time dependencies:

```python build-constraints.txt theme={null}
setuptools==75.0.0
```

```toml pyproject.toml theme={null}
[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"
```

Applies to all build-time dependencies in the workspace.

### Overriding versions

Force specific versions regardless of declared requirements:

```python overrides.txt theme={null}
c>=2.0
```

```bash theme={null}
uv pip compile requirements.in --override overrides.txt
```

<Warning>
  Overrides replace constituent package requirements completely. Use when transitive dependencies have incorrect bounds, but be aware this may cause runtime errors if the override is incorrect.
</Warning>

## Migrating from pip

### Common command mappings

<AccordionGroup>
  <Accordion title="Install commands">
    ```bash theme={null}
    # pip
    pip install requests
    pip install -r requirements.txt
    pip install -e .

    # uv
    uv pip install requests
    uv pip install -r requirements.txt
    uv pip install -e .
    ```
  </Accordion>

  <Accordion title="Uninstall commands">
    ```bash theme={null}
    # pip
    pip uninstall requests

    # uv
    uv pip uninstall requests
    ```
  </Accordion>

  <Accordion title="List and inspect">
    ```bash theme={null}
    # pip
    pip list
    pip freeze
    pip show requests

    # uv
    uv pip list
    uv pip freeze
    uv pip show requests
    ```
  </Accordion>

  <Accordion title="Virtual environments">
    ```bash theme={null}
    # venv
    python -m venv .venv

    # virtualenv
    virtualenv .venv

    # uv
    uv venv
    ```
  </Accordion>
</AccordionGroup>

### Migrating from pip-tools

<AccordionGroup>
  <Accordion title="Compiling requirements">
    ```bash theme={null}
    # pip-compile
    pip-compile requirements.in
    pip-compile pyproject.toml --extra dev

    # uv
    uv pip compile requirements.in -o requirements.txt
    uv pip compile pyproject.toml --extra dev -o requirements.txt
    ```
  </Accordion>

  <Accordion title="Syncing environments">
    ```bash theme={null}
    # pip-sync
    pip-sync requirements.txt

    # uv
    uv pip sync requirements.txt
    ```
  </Accordion>

  <Accordion title="Upgrading packages">
    ```bash theme={null}
    # pip-compile
    pip-compile requirements.in --upgrade
    pip-compile requirements.in --upgrade-package requests

    # uv
    uv pip compile requirements.in --upgrade -o requirements.txt
    uv pip compile requirements.in --upgrade-package requests -o requirements.txt
    ```
  </Accordion>
</AccordionGroup>

### Complete migration workflow

<Steps>
  <Step title="Create environment">
    ```bash theme={null}
    # Before: python -m venv .venv
    uv venv
    ```
  </Step>

  <Step title="Activate environment">
    ```bash theme={null}
    source .venv/bin/activate  # Same as before
    ```
  </Step>

  <Step title="Compile requirements">
    ```bash theme={null}
    # Before: pip-compile requirements.in
    uv pip compile requirements.in -o requirements.txt
    ```
  </Step>

  <Step title="Install packages">
    ```bash theme={null}
    # Before: pip install -r requirements.txt
    uv pip install -r requirements.txt
    ```
  </Step>

  <Step title="Sync environment">
    ```bash theme={null}
    # Before: pip-sync requirements.txt
    uv pip sync requirements.txt
    ```
  </Step>
</Steps>

## Universal resolution

Unlike pip and pip-tools, uv can compile requirements for multiple platforms at once:

```bash theme={null}
uv pip compile --universal requirements.in
```

This creates a single `requirements.txt` that works across platforms:

```python requirements.txt theme={null}
colorama==0.4.6 ; sys_platform == 'win32'
    # via tqdm
tqdm==4.67.1
    # via -r requirements.in
```

No need for separate requirements files per platform!

See [universal resolution](../concepts/resolution.md#universal-resolution) for details.

## Best practices

<AccordionGroup>
  <Accordion title="Use uv pip sync for reproducibility">
    `uv pip sync` ensures exact environment matches:

    ```bash theme={null}
    uv pip sync requirements.txt
    ```

    Unlike `pip install -r`, this removes extraneous packages.
  </Accordion>

  <Accordion title="Lock for multiple platforms">
    Use `--universal` for cross-platform projects:

    ```bash theme={null}
    uv pip compile --universal requirements.in -o requirements.txt
    ```
  </Accordion>

  <Accordion title="Separate development dependencies">
    Use multiple requirements files:

    ```python requirements-dev.in theme={null}
    -r requirements.in
    -c requirements.txt
    pytest
    ruff
    ```

    Then compile:

    ```bash theme={null}
    uv pip compile requirements-dev.in -o requirements-dev.txt
    ```
  </Accordion>

  <Accordion title="Consider migrating to projects">
    For new work, [uv projects](./projects.mdx) provide:

    * Automatic environment management
    * Cross-platform lockfiles by default
    * Simplified dependency management
    * No manual activation needed
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="pip compatibility" icon="scale-balanced" href="../pip/compatibility.md">
    Understand differences from pip
  </Card>

  <Card title="Migration guide" icon="arrow-right" href="../guides/migration/pip-to-project.md">
    Migrate from pip to uv projects
  </Card>

  <Card title="Working with projects" icon="folder" href="./projects.mdx">
    Use uv's project interface instead
  </Card>

  <Card title="pip interface docs" icon="book" href="../pip/index.md">
    Full pip interface documentation
  </Card>
</CardGroup>