Python Package Management with uv

AI summary

uv is a fast Python package and project manager that replaces multiple tools like pip and poetry. It offers built-in virtual environment and Python version management, supports lock files for reproducibility, and optimizes disk space usage. Key features include easy installation, efficient package management, and advanced commands for dependency and cache management. Best practices emphasize using virtual environments, pinning Python versions, and utilizing lock files for production setups.

Type

📚 Table of Contents

Introduction to uv
Installation & Setup
Virtual Environment Management
Activation & Deactivation
Package Installation & Management
Dependency Management
Python Version Management
Project Initialization & Structure
Advanced Features & Commands
Configuration & Customization
Migration from pip/venv/poetry
Complete Workflows
Troubleshooting & Common Issues
Performance & Optimization
Best Practices & Tips

1. Introduction to uv

What is uv?

uv is an extremely fast Python package and project manager written in Rust by Astral (the team behind Ruff). It's designed as a complete replacement for multiple Python tools: pip, pip-tools, pipx, poetry, pyenv, and virtualenv.

Why uv?

Speed: 10-100x faster than traditional tools

Virtual Environments: Built-in, instant creation

Python Management: Built-in version management

Lock Files: Native support for reproducible environments

Disk Space: Global cache saves 50-70% space

Tool Management: Built-in tool management with uvx

Core Philosophy

Speed: Written in Rust for maximum performance
Simplicity: One tool for all Python package management needs
Compatibility: Works with existing Python standards (PEP 517, 621, etc.)
Reliability: Lock files ensure reproducible environments
Efficiency: Global cache prevents duplicate downloads

What uv Replaces

pip            → uv pip
pip-tools      → uv pip compile
virtualenv     → uv venv
pyenv          → uv python
pipx           → uv tool / uvx
poetry         → uv (with pyproject.toml)
pip-sync       → uv sync

2. Installation & Setup

Installation Methods

Linux/Mac (Official Installer):

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Using pip:

pip install uv

Homebrew (Mac):

brew install uv

Verify Installation

# Check version
uv --version

# Check all available commands
uv --help

Update uv

# Self-update to latest version
uv self update

3. Virtual Environment Management

Complete Directory Structure

When you create a virtual environment with uv venv, here's what you get:

.venv/
├── .gitignore              # Auto-generated to prevent Git commits
├── CACHEDIR.TAG            # Marks directory for backup tools
├── pyvenv.cfg              # Virtual environment configuration
├── bin/ (or Scripts/)      # Executables and activation scripts
├── lib/python3.X/site-packages/  # Where packages are installed
└── include/                # C header files for extensions

Key Files Explained:

.gitignore: Prevents accidental Git commits (contains *)
CACHEDIR.TAG: Identifies as cache for backup tools
pyvenv.cfg: Configuration with Python version and paths
bin/ or Scripts/: Python interpreter and all executable scripts
site-packages/: Where all Python packages are installed

Creating Virtual Environments

# Create default virtual environment named .venv
uv venv

# Create with custom name
uv venv myenv

# Create with specific Python version (auto-installs if needed!)
uv venv --python 3.11

# Create with system site-packages access
uv venv --system-site-packages

Manage Virtual Environments

# Rename (deactivate first)
deactivate
mv .venv new_env_name

# Delete
rm -rf .venv

4. Activation & Deactivation

Activation

Linux/Mac (Bash/Zsh):

source .venv/bin/activate

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Windows (Command Prompt):

.venv\Scripts\activate.bat

Verify Activation

When activated, your prompt changes to:

(.venv) user@machine:~/project$

Check Python location:

which python  # Linux/Mac
where python  # Windows

Deactivation

deactivate

5. Package Installation & Management

Basic Installation

# Install single package
uv pip install numpy

# Install specific version
uv pip install numpy==1.26.0

# Install multiple packages
uv pip install numpy pandas matplotlib

# Install with version range
uv pip install "pandas>=2.0.0,<3.0.0"

Essential Data Science Packages

Development Tools:

uv pip install notebook ipython ipykernel marimo jupytext pyarrow watchdog

Core Data Science Stack:

uv pip install numpy pandas matplotlib seaborn scikit-learn scipy

Visualization:

uv pip install plotly altair

Machine Learning:

uv pip install torch torchvision torchaudio xgboost lightgbm

Code Quality Tools:

uv pip install black ruff isort mypy pytest

Package Management Commands

# List installed packages
uv pip list

# Show package details
uv pip show pandas

# Show dependency tree
uv pip tree

# Upgrade package
uv pip install --upgrade pandas

# Uninstall package
uv pip uninstall numpy

# Check for conflicts
uv pip check

6. Dependency Management

Using requirements.txt

# Generate requirements.txt
uv pip freeze > requirements.txt

# Install from requirements.txt
uv pip install -r requirements.txt

# View requirements
cat requirements.txt

Using Lock Files (Advanced)

# Compile requirements.in to locked requirements.txt
uv pip compile requirements.in -o requirements.txt

# Update locked dependencies
uv pip compile requirements.in --upgrade -o requirements.txt

# Sync environment to exactly match lock file
uv pip sync requirements.txt

Using pyproject.toml (Modern)

Create pyproject.toml:

[project]
name = "my-data-project"
version = "0.1.0"
requires-python = ">=3.10"

dependencies = [
    "pandas>=2.0.0",
    "numpy>=1.24.0",
    "matplotlib>=3.7.0",
]

[project.optional-dependencies]
dev = [
    "black>=23.0.0",
    "pytest>=7.4.0",
]

Install:

# Install main dependencies
uv pip install -e .

# Install with dev dependencies
uv pip install -e ".[dev]"

7. Python Version Management

List & Install Python Versions

# Show available Python versions
uv python list

# Show only installed versions
uv python list --only-installed

# Install Python 3.11 (auto-downloads!)
uv python install 3.11

# Install specific version
uv python install 3.11.7

Pin Python Version

# Pin to Python 3.11 for current project
uv python pin 3.11

# This creates .python-version file
# Now uv venv will use Python 3.11 automatically!

Find & Uninstall

# Find specific Python version
uv python find 3.11

# Uninstall Python version
uv python uninstall 3.10

8. Project Initialization & Structure

Initialize New Project

# Initialize new Python project
uv init my-project

# This creates:
# my-project/
# ├── README.md
# ├── pyproject.toml
# ├── src/my_project/__init__.py
# └── tests/__init__.py

Recommended Project Structure

my-data-project/
├── .venv/                    # Virtual environment
├── .python-version           # Pinned Python version
├── .gitignore
├── README.md
├── pyproject.toml           # Project configuration
├── requirements.txt         # Locked dependencies
├── src/my_project/          # Source code
├── notebooks/               # Jupyter notebooks
├── data/                    # Data files
├── tests/                   # Tests
└── scripts/                 # Utility scripts

9. Advanced Features & Commands

Global Tool Management

# Install tool globally
uv tool install black

# List global tools
uv tool list

# Upgrade tool
uv tool upgrade black

# Uninstall tool
uv tool uninstall black

Run Without Installing (uvx)

# Run black without installing
uvx black my_script.py

# Run with specific version
uvx --from black==23.0.0 black .

# Run ruff linter
uvx ruff check .

# Run pytest
uvx pytest tests/

Cache Management

# Show cache directory and size
uv cache info

# Clean entire cache
uv cache clean

# Clean specific package
uv cache clean pandas

# Prune old cache entries
uv cache prune --age 30d

Sync Dependencies

# Sync to match requirements.txt exactly
# Installs missing, upgrades outdated, removes extras
uv pip sync requirements.txt

10. Configuration & Customization

Environment Variables

# Cache directory
export UV_CACHE_DIR=/custom/cache/path

# Concurrent downloads (default 50)
export UV_CONCURRENT_DOWNLOADS=100

# Python preference
export UV_PYTHON_PREFERENCE=managed

# Link mode (copy, hardlink, symlink)
export UV_LINK_MODE=hardlink

Add to ~/.bashrc or ~/.zshrc:

export UV_CACHE_DIR="$HOME/.cache/uv"
export UV_CONCURRENT_DOWNLOADS=100

Project Configuration (uv.toml)

Create uv.toml in project root:

[tool.uv]
python-version = "3.11"
index-url = "https://pypi.org/simple"
compile = true

11. Migration from pip/venv/poetry

From pip + venv

Old Command	New uv Command
`python -m venv .venv`	`uv venv`
`pip install numpy`	`uv pip install numpy`
`pip install -r requirements.txt`	`uv pip install -r requirements.txt`
`pip freeze > requirements.txt`	`uv pip freeze > requirements.txt`
`pip list`	`uv pip list`

Migration Steps

# 1. Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Navigate to project
cd my-project

# 3. Create new venv with uv
uv venv

# 4. Activate
source .venv/bin/activate

# 5. Install from existing requirements.txt
uv pip install -r requirements.txt

# 6. Pin Python version
uv python pin 3.11

# Done!

12. Complete Workflows

Workflow 1: Quick Data Science Project

# 1. Create project
mkdir customer-analysis && cd customer-analysis

# 2. Pin Python
uv python pin 3.11

# 3. Create venv
uv venv

# 4. Activate
source .venv/bin/activate

# 5. Install data science stack
uv pip install numpy pandas matplotlib seaborn scikit-learn jupyter

# 6. Install dev tools
uv pip install black ruff ipykernel

# 7. Register Jupyter kernel
python -m ipykernel install --user --name=customer-analysis

# 8. Generate requirements
uv pip freeze > requirements.txt

# 9. Start Jupyter
jupyter notebook

Workflow 2: Production Project with Lock Files

# 1. Initialize project
uv init ml-service
cd ml-service

# 2. Pin Python
uv python pin 3.11

# 3. Edit pyproject.toml (add dependencies)

# 4. Create venv
uv venv

# 5. Activate
source .venv/bin/activate

# 6. Install with dev dependencies
uv pip install -e ".[dev]"

# 7. Generate lock file
uv pip compile pyproject.toml --all-extras -o requirements.lock

# 8. Sync environment
uv pip sync requirements.lock

# 9. Run tests
pytest tests/

Workflow 3: Team Collaboration

Repository Setup:

uv init team-project
cd team-project
uv python pin 3.11
# Create pyproject.toml with dependencies
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
uv pip compile pyproject.toml --all-extras -o requirements.lock
git init && git add . && git commit -m "Initial setup"

Team Member Setup:

git clone repo-url
cd team-project
uv venv  # Uses .python-version automatically
source .venv/bin/activate
uv pip sync requirements.lock  # Exact same environment!

13. Troubleshooting & Common Issues

"uv: command not found"

# Add to PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Add to shell config
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Python version not found"

# Install missing Python version
uv python install 3.11

# Or use system Python
uv venv --python system

Dependency Conflicts

# Check for conflicts
uv pip check

# Show dependency tree
uv pip tree

# Use constraints file
cat > constraints.txt << EOF
numpy<2.0.0
pandas>=2.0.0,<3.0.0
EOF

uv pip install -r requirements.txt -c constraints.txt

Virtual Environment Won't Activate

# Make activate executable
chmod +x .venv/bin/activate

# Try absolute path
source $(pwd)/.venv/bin/activate

# Recreate if corrupted
rm -rf .venv
uv venv

14. Performance & Optimization

Speed Benchmarks

Typical performance installing pandas + dependencies:

pip: ~45 seconds (cold), ~15 seconds (warm)
uv: ~3 seconds (cold), ~0.5 seconds (warm)
Speedup: 15x faster (cold), 30x faster (warm)

Optimization Tips

1. Use Link Mode:

export UV_LINK_MODE=hardlink  # Fastest, saves space

2. Increase Concurrent Downloads:

export UV_CONCURRENT_DOWNLOADS=100

3. Use Lock Files:

# Lock files prevent re-resolving
uv pip sync requirements.txt  # Faster than install

4. Leverage Cache:

# Check cache stats
uv cache info

# Cache is automatic and shared across projects

15. Best Practices & Tips

✅ DO

Always use virtual environments

uv venv  # For each project

Pin Python versions

uv python pin 3.11

Use lock files for production

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

Add .venv to .gitignore

.venv/
__pycache__/
*.pyc

Use uvx for one-off commands

uvx black .  # No installation needed

Document your setup in README
Use semantic versioning

pandas>=2.0.0,<3.0.0

❌ DON'T

Don't commit virtual environments - Add to .gitignore
Don't use sudo with uv - Virtual environments don't need root
Don't mix package managers - Choose uv OR pip, not both
Don't forget to activate - Always activate before installing
Don't install packages globally - Use virtual environments
Don't ignore dependency conflicts - Run uv pip check regularly

🎯 Pro Tips

Shell Aliases (add to .bashrc or .zshrc):

alias va='source .venv/bin/activate'
alias vd='deactivate'
alias ve='uv venv'
alias pi='uv pip install'
alias pu='uv pip uninstall'
alias pf='uv pip freeze'

Quick Environment Setup:

# One-liner for new project
uv venv && source .venv/bin/activate && uv pip install numpy pandas matplotlib jupyter

📋 Quick Command Reference

# Installation
curl -LsSf https://astral.sh/uv/install.sh | sh

# Virtual Environments
uv venv                          # Create .venv
uv venv --python 3.11           # With specific Python
source .venv/bin/activate        # Activate
deactivate                       # Deactivate

# Package Management
uv pip install numpy            # Install package
uv pip install -r requirements.txt
uv pip uninstall numpy
uv pip list
uv pip freeze > requirements.txt
uv pip sync requirements.txt
uv pip check

# Python Management
uv python list
uv python install 3.11
uv python pin 3.11

# Tools
uvx black .                     # Run without installing
uv tool install black           # Install globally

# Cache
uv cache info
uv cache clean

# Project
uv init my-project

🚀 Getting Started Checklist

Install uv

Verify installation (uv --version)

Create first virtual environment

Install favorite packages

Generate requirements.txt

Learn to use lock files

Set up shell aliases

Configure .gitignore

Pin Python version for project

Share with team!

📚 Additional Resources

Official Documentation: https://docs.astral.sh/uv/
GitHub Repository: https://github.com/astral-sh/uv
Release Notes: https://github.com/astral-sh/uv/releases
Discord Community: https://discord.gg/astral-sh

This comprehensive guide covers everything from basic installation to advanced workflows. Start with the basics (sections 1-6), then explore advanced features as needed. Happy coding with uv! 🐍✨