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.

The uv pip interface operates at a lower level than uv’s primary project interface. For new projects, consider using projects instead.

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 for details.

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.

Creating and using environments

Creating virtual environments

Create a virtual environment like python -m venv:

uv venv

This creates a .venv directory in the current location.

Custom name

uv venv myenv

uv venv --python 3.11

uv venv --python /usr/bin/python3.10

Activating environments

After creating, activate the environment:

macOS / Linux

source .venv/bin/activate

.venv\Scripts\activate

.venv\Scripts\activate.bat

See creating environments for more details.

Installing and managing packages

Installing packages

1. Install a single package

   uv pip install flask
   
2. Install with extras

   uv pip install "flask[dotenv]"
   
3. Install multiple packages

   uv pip install flask ruff
   
4. Install with constraints

   uv pip install 'ruff>=0.2.0'
   

Installing from different sources

Specific version

uv pip install 'ruff==0.3.0'

uv pip install "ruff @ ./projects/ruff"

uv pip install "git+https://github.com/astral-sh/ruff"

uv pip install "git+https://github.com/astral-sh/ruff@v0.2.0"

See Git authentication for private repositories.

Editable packages

Install packages in editable mode:

Current directory

uv pip install -e .

uv pip install -e "ruff @ ./project/ruff"

Changes to source code are immediately active.

Installing from files

Install from various file formats:

requirements.txt

uv pip install -r requirements.txt

uv pip install -r pyproject.toml

uv pip install -r pyproject.toml --extra foo

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

Installing dependency groups

Install groups from pyproject.toml:

Single group

uv pip install --group foo

uv pip install --group foo --group bar

uv pip install --project some/path/ --group foo

uv pip install --group some/path/pyproject.toml:foo

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

Uninstalling packages

Single package

uv pip uninstall flask

uv pip uninstall flask ruff

See managing packages for more details.

Locking and syncing environments

Locking requirements

Generate a locked requirements.txt:

From pyproject.toml

uv pip compile pyproject.toml -o requirements.txt

uv pip compile requirements.in -o requirements.txt

uv pip compile pyproject.toml requirements-dev.in -o requirements-dev.txt

echo "ruff" | uv pip compile -

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

Compiling with extras

Single extra

uv pip compile pyproject.toml --extra foo

uv pip compile pyproject.toml --all-extras

uv pip compile --group foo

A --group flag was added to uv pip compile, though pip-tools is considering it. We’ll support whatever syntax they adopt.

Upgrading requirements

uv respects existing pinned versions in output files:

echo "ruff==0.3.0" > requirements.txt
echo "ruff" | uv pip compile - -o requirements.txt
# ruff==0.3.0  (unchanged)

Upgrade specific packages:

uv pip compile requirements.in -o requirements.txt --upgrade-package ruff

Or upgrade everything:

uv pip compile requirements.in -o requirements.txt --upgrade

Syncing environments

Sync environment to exactly match a lockfile:

requirements.txt

uv pip sync requirements.txt

uv pip sync pylock.toml

uv pip install keeps existing packages that don’t conflict. uv pip sync removes any packages not in the lockfile, ensuring exact reproducibility.

See locking environments for more details.

Inspecting environments and packages

List installed packages

All packages

uv pip list

uv pip freeze

uv pip show flask

Check package information

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 for more details.

Working with constraints and overrides

Adding constraints

Constraint files control versions without triggering installation:

constraints.txt

pydantic<2.0

uv pip compile requirements.in --constraint constraints.txt

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

Build constraints

Constrain build-time dependencies:

build-constraints.txt

setuptools==75.0.0

pyproject.toml

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

overrides.txt

c>=2.0

uv pip compile requirements.in --override overrides.txt

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.

Migrating from pip

Common command mappings

Install commands

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

Uninstall commands

# pip
pip uninstall requests

# uv
uv pip uninstall requests

List and inspect

# pip
pip list
pip freeze
pip show requests

# uv
uv pip list
uv pip freeze
uv pip show requests

Virtual environments

# venv
python -m venv .venv

# virtualenv
virtualenv .venv

# uv
uv venv

Migrating from pip-tools

Compiling requirements

# 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

Syncing environments

# pip-sync
pip-sync requirements.txt

# uv
uv pip sync requirements.txt

Upgrading packages

# 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

Complete migration workflow

1. Create environment

   # Before: python -m venv .venv
   uv venv
   
2. Activate environment

   source .venv/bin/activate  # Same as before
   
3. Compile requirements

   # Before: pip-compile requirements.in
   uv pip compile requirements.in -o requirements.txt
   
4. Install packages

   # Before: pip install -r requirements.txt
   uv pip install -r requirements.txt
   
5. Sync environment

   # Before: pip-sync requirements.txt
   uv pip sync requirements.txt
   

Universal resolution

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

uv pip compile --universal requirements.in

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

requirements.txt

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 for details.

Best practices

Use uv pip sync for reproducibility

uv pip sync ensures exact environment matches:

uv pip sync requirements.txt

Unlike pip install -r, this removes extraneous packages.

Lock for multiple platforms

Use --universal for cross-platform projects:

uv pip compile --universal requirements.in -o requirements.txt

Separate development dependencies

Use multiple requirements files:

requirements-dev.in

-r requirements.in
-c requirements.txt
pytest
ruff

Then compile:

uv pip compile requirements-dev.in -o requirements-dev.txt

Consider migrating to projects

For new work, uv projects provide:

• Automatic environment management
• Cross-platform lockfiles by default
• Simplified dependency management
• No manual activation needed

Next steps

pip compatibility

Understand differences from pip

Migration guide

Migrate from pip to uv projects

Working with projects

Use uv’s project interface instead

pip interface docs

Full pip interface documentation