UV Python Package Manager Guide

Resources

• UV Official Documentation
• UV vs Pip Performance Comparison
• Python Packaging Best Practices

What is UV?

UV is a fast Python package installer and resolver developed by Astral, written in Rust. Designed as a modern alternative to pip and pip-tools, it offers significantly faster dependency resolution and package installation. UV is fully compatible with pip, allowing it to seamlessly replace existing pip commands while delivering substantial performance improvements.

Why Use UV?

• Ultra-fast Installation: 10-100x faster than traditional pip
• Parallel Downloads: Simultaneously downloads multiple packages to save time
• Smart Caching: Efficiently caches downloaded packages
• Compatibility: Fully compatible with existing pip commands and workflows
• Better Dependency Resolution: Avoids dependency conflicts for more reliable environments

Installing UV

Installing UV is straightforward:

pip install uv

Basic Usage

0. Simple Mode

Installing Packages

Single package installation:

uv pip install numpy

Installing from requirements.txt:

uv pip install -r requirements.txt

Installing specific versions:

uv pip install pandas==2.0.3

Uninstalling Packages

uv pip uninstall numpy

Listing Installed Packages

uv pip list

Upgrading Packages

uv pip install --upgrade numpy

Dependency Management

Generating requirements.txt:

uv pip freeze > requirements.txt

Virtual Environment Management

UV provides powerful virtual environment management capabilities, making it easy to create and manage environments with different Python versions.

Creating Virtual Environments

Creating a default environment:

uv venv .venv

Specifying a Python version:

uv venv --python=3.11 .venv311

Using a specific Python interpreter from your system:

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

Activating Virtual Environments

On Linux/macOS:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Installing Packages in Virtual Environments

Creating and installing dependencies in an environment:

uv venv .venv
uv pip install -r requirements.txt --venv .venv

Project Mode

uv init PROJECT_NAME

Advanced UV Features

Using pyproject.toml

UV supports installing development dependencies from pyproject.toml:

uv pip install -e .

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

Syncing Dependencies

Ensuring your environment exactly matches requirements.txt:

uv pip sync requirements.txt

Accelerating with Parallel Installation

UV uses parallel installation by default, but you can adjust the parallelism:

uv pip install -r requirements.txt --jobs 16

Repository Mirror Configuration

Using alternative package repositories for a single installation:

uv pip install numpy -i https://pypi.org/simple

Global Mirror Configuration

To set up global mirror configuration for UV, you can use environment variables or configuration files:

Method 1: Environment Variables

Set the default index URL globally:

export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"

For permanent configuration, add this to your shell profile (.bashrc, .zshrc, etc.):

echo 'export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.bashrc
source ~/.bashrc

Method 2: Configuration File

Create a UV configuration file at ~/.config/uv/uv.toml (Linux/macOS) or %APPDATA%\uv\uv.toml (Windows):

[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

# Optional: Add extra index URLs
extra-index-url = [
    "https://pypi.org/simple",
    "https://download.pytorch.org/whl/cpu"
]

Method 3: Project-specific Configuration

For project-specific mirror settings, add to your pyproject.toml:

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

[[tool.uv.index]]
url = "https://pypi.org/simple"

Common Mirror URLs:

• Tsinghua University: https://pypi.tuna.tsinghua.edu.cn/simple
• Alibaba Cloud: https://mirrors.aliyun.com/pypi/simple
• Douban: https://pypi.douban.com/simple
• USTC: https://pypi.mirrors.ustc.edu.cn/simple

Performance Optimization Tips

1. Leverage UV’s caching to reduce repeated downloads
2. Use uv pip compile to generate lock files for large projects
3. Utilize the --jobs parameter to adjust parallelism for your system’s capabilities

Comparison with Other Tools

Feature	UV	pip	pip-tools	Poetry
Installation Speed	Extremely Fast	Slow	Moderate	Moderate
Dependency Resolution	Precise	Basic	Good	Good
Virtual Environment Management	Supported	Not Supported	Not Supported	Supported
Compatibility	High	High	High	Moderate
Parallel Downloads	On by Default	Not Supported	Not Supported	Supported

Troubleshooting Common Issues

UV Installation Failures

If you encounter issues installing UV, try:

pip install --upgrade pip
pip install uv --no-cache-dir

Dependency Resolution Conflicts

When facing dependency resolution conflicts:

uv pip install package-a package-b --strict

Using the --strict parameter provides more detailed conflict information.