Skip to main content

​
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. 
uv venv myenv

​
Activating environments

After creating, activate the environment: 
source .venv/bin/activate
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

uv pip install 'ruff==0.3.0'
See Git authentication for private repositories.

​
Editable packages

Install packages in editable mode: 
uv pip install -e .
Changes to source code are immediately active.

​
Installing from files

Install from various file formats: 
uv pip install -r requirements.txt

​
Installing dependency groups

Install groups from pyproject.toml: 
uv pip install --group 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

uv pip uninstall flask
See managing packages for more details.

​
Locking and syncing environments

​
Locking requirements

Generate a locked requirements.txt: 
uv pip compile pyproject.toml -o requirements.txt
By default, uv pip compile prints output to stdout. Use -o / --output-file to write to a file.

​
Compiling with extras

uv pip compile pyproject.toml --extra 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: 
uv pip sync requirements.txt
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

uv pip list

​
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

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

# pip
pip uninstall requests

# uv
uv pip uninstall requests

# pip
pip list
pip freeze
pip show requests

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

# venv
python -m venv .venv

# virtualenv
virtualenv .venv

# uv
uv venv

​
Migrating from pip-tools

# 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

# pip-sync
pip-sync requirements.txt

# uv
uv pip sync requirements.txt

# 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

uv pip sync ensures exact environment matches:
uv pip sync requirements.txt
Unlike pip install -r, this removes extraneous packages.
Use --universal for cross-platform projects:
uv pip compile --universal requirements.in -o requirements.txt
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us