uv Python Package Manager

uv cheatsheet — blazing-fast Python package manager and venv tool. uv pip install, uv venv, uv add, uv run, uv sync. 10-100x faster than pip, written in Rust.

6 min read

What it is

uv is a fast, modern Python package installer and virtual environment manager written in Rust, designed to be a drop-in replacement for pip and venv.

Installation

Linux / macOS

curl -LsSf https://github.com/astral-sh/uv/releases/download/v0.1.10/uv-linux_x86_64.tar.gz | tar xz
sudo mv uv /usr/local/bin/

(Replace linux_x86_64 with your architecture if needed, e.g., macos_arm64 for Apple Silicon Macs.)

Windows (PowerShell)

Invoke-WebRequest -Uri https://github.com/astral-sh/uv/releases/download/v0.1.10/uv-windows_x86_64.zip -OutFile uv.zip
Expand-Archive uv.zip
# Move uv.exe to a directory in your PATH, e.g., C:\Users\YourUser\bin
# or add the directory where uv.exe is to your PATH.

Core Concepts

Resolution

uv uses a sophisticated dependency resolver that aims to be faster and more reliable than pip’s. It can resolve dependencies for multiple Python versions simultaneously.

Virtual Environments

uv can create and manage virtual environments, offering a unified interface for both dependency installation and environment management.

Lock Files

uv supports lock files (uv.lock) to ensure reproducible builds by pinning exact versions of all installed packages and their dependencies.

Commands / Usage

Creating and Managing Virtual Environments

Create a virtual environment:
```
uv venv
```
Creates a virtual environment named .venv in the current directory.
Create a virtual environment with a specific Python interpreter:
```
uv venv --python 3.11
```
Creates a virtual environment using the python3.11 interpreter found in your PATH.
Create a virtual environment in a specific directory:
```
uv venv --path /path/to/my/env
```
Creates a virtual environment at the specified path.
List available virtual environments:
```
uv venv --list
```
Shows all virtual environments managed by uv in the current project.
Remove a virtual environment:
```
uv venv --remove
```
Removes the .venv environment in the current directory.

Activate a virtual environment (shell-specific):

Bash/Zsh:
```
source .venv/bin/activate
```
Fish:
```
source .venv/bin/activate.fish
```
PowerShell:
```
.venv\Scripts\Activate.ps1
```

Deactivate a virtual environment:
```
deactivate
```
(This command is provided by the virtual environment’s activation script.)

Installing and Managing Packages

Install packages from requirements.txt:
```
uv pip install -r requirements.txt
```
Installs packages listed in requirements.txt.
Install a specific package:
```
uv pip install requests
```
Installs the latest version of the requests package.
Install a specific version of a package:
```
uv pip install 'requests==2.28.1'
```
Installs version 2.28.1 of the requests package.
Install packages from pyproject.toml (as a package):
```
uv pip install .
```
Installs the current project and its dependencies.
Install packages in editable mode:
```
uv pip install -e .
```
Installs the current project in editable mode.
Install packages and generate a lock file:
```
uv pip compile requirements.in --output-file requirements.txt
```
Compiles dependencies from requirements.in and writes the exact versions to requirements.txt.
Install packages from a lock file:
```
uv pip install -r requirements.txt
```
Installs packages based on the exact versions specified in requirements.txt.
Uninstall a package:
```
uv pip uninstall requests
```
Uninstalls the requests package.
Uninstall all packages:
```
uv pip uninstall -y --all
```
Uninstalls all packages from the current environment.
Update packages:
```
uv pip install --upgrade requests
```
Upgrades the requests package to the latest compatible version.
List installed packages:
```
uv pip list
```
Lists all packages currently installed in the environment.
Show package details:
```
uv pip show requests
```
Displays detailed information about the requests package.
Check for package updates:
```
uv pip list --outdated
```
Lists packages that have newer versions available.

Syncing Environments

Sync dependencies from requirements.txt to the environment:
```
uv pip sync requirements.txt
```
Ensures the environment exactly matches the dependencies in requirements.txt, installing missing and uninstalling extra packages.

Building Wheels

Build wheels for the current project:
```
uv pip wheel .
```
Builds wheel files for the project in the current directory.

Configuration

Set a default Python interpreter:
```
uv cache set python-version 3.11
```
Sets 3.11 as the default Python version for uv to use when creating environments or resolving dependencies.
Clear the uv cache:
```
uv cache clear
```
Removes all cached wheels and downloaded packages.
Show cache information:
```
uv cache info
```
Displays details about the uv cache directory and its contents.

Other Commands

Run a Python script with uv:
```
uv python script.py
```
Executes script.py within a uv-managed environment (if one exists or is created).
Run a Python interpreter with uv:
```
uv python
```
Starts an interactive Python interpreter within a uv-managed environment.
Get uv version:
```
uv --version
```
Displays the installed version of uv.
Show uv help:
```
uv --help
```
Displays general help information for uv.
Show uv pip help:
```
uv pip --help
```
Displays help information specifically for the uv pip subcommand.

Common Patterns

Setting up a new project with `uv`

Create a virtual environment:
```
uv venv
```
Activate the environment:
```
source .venv/bin/activate
```
Install initial dependencies (e.g., from a requirements.in file):
```
uv pip install -r requirements.in
```

Generate a lock file for reproducibility:

uv pip compile requirements.in --output-file requirements.txt

Install from the lock file for future installs:
```
uv pip install -r requirements.txt
```

Using `uv` with `pyproject.toml`

If your project uses pyproject.toml for build backend configuration:

# Install project dependencies and the project itself
uv pip install .

# Install project dependencies in editable mode
uv pip install -e .

# Sync the environment to match project dependencies
uv pip sync .

Migrating from `pip`

If you have an existing project using pip and requirements.txt:

Ensure uv is installed.
Create or activate your existing virtual environment.
Run uv pip install -r requirements.txt to install packages using uv.
Optionally, generate a lock file: uv pip compile requirements.txt --output-file requirements.lock and then use uv pip install -r requirements.lock for future installations.

Installing packages for multiple Python versions

uv can resolve dependencies across different Python versions. If you need to install a package that has different requirements for different Python versions, uv can handle this during resolution. For explicit environment management with multiple Python versions, you would typically manage separate virtual environments for each version.

Gotchas

Virtual Environment Location

By default, uv venv creates a .venv directory in the current working directory. If you run uv commands from different subdirectories within a project, it might try to manage the same .venv or create new ones unexpectedly if not careful. It’s best to run uv commands from the project root.

`uv` vs. `pip` commands

While uv pip aims to be a drop-in replacement, there might be subtle differences in behavior or support for very obscure pip features. For most common use cases, it’s a seamless transition.

Python Interpreter Discovery

uv looks for Python interpreters in your system’s PATH. If you have multiple Python versions installed and need to target a specific one for a virtual environment, ensure it’s discoverable or specify it using the --python flag.

Lock File Generation

uv pip compile is the idiomatic way to generate lock files. Directly using uv pip install without a lock file will install the latest compatible versions, which can lead to less reproducible builds compared to installing from a generated lock file.

Shell Activation

The activation scripts for virtual environments are shell-specific. Make sure you use the correct activation command for your shell (e.g., source for Bash/Zsh, .ps1 for PowerShell).