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.
📚 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 sync2. Installation & Setup
Installation Methods
Linux/Mac (Official Installer):
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"Using pip:
pip install uvHomebrew (Mac):
brew install uvVerify Installation
# Check version
uv --version
# Check all available commands
uv --helpUpdate uv
# Self-update to latest version
uv self update3. 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 extensionsKey Files Explained:
.gitignore: Prevents accidental Git commits (contains*)CACHEDIR.TAG: Identifies as cache for backup toolspyvenv.cfg: Configuration with Python version and pathsbin/orScripts/: Python interpreter and all executable scriptssite-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-packagesManage Virtual Environments
# Rename (deactivate first)
deactivate
mv .venv new_env_name
# Delete
rm -rf .venv4. Activation & Deactivation
Activation
Linux/Mac (Bash/Zsh):
source .venv/bin/activateWindows (PowerShell):
.venv\Scripts\Activate.ps1Windows (Command Prompt):
.venv\Scripts\activate.batVerify Activation
When activated, your prompt changes to:
(.venv) user@machine:~/project$Check Python location:
which python # Linux/Mac
where python # WindowsDeactivation
deactivate5. 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 watchdogCore Data Science Stack:
uv pip install numpy pandas matplotlib seaborn scikit-learn scipyVisualization:
uv pip install plotly altairMachine Learning:
uv pip install torch torchvision torchaudio xgboost lightgbmCode Quality Tools:
uv pip install black ruff isort mypy pytestPackage 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 check6. 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.txtUsing 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.txtUsing 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.7Pin 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.108. 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__.pyRecommended Project Structure
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 blackRun 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 30dSync Dependencies
# Sync to match requirements.txt exactly
# Installs missing, upgrades outdated, removes extras
uv pip sync requirements.txt10. 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=hardlinkAdd to ~/.bashrc or ~/.zshrc:
export UV_CACHE_DIR="$HOME/.cache/uv"
export UV_CONCURRENT_DOWNLOADS=100Project Configuration (uv.toml)
Create uv.toml in project root:
[tool.uv]
python-version = "3.11"
index-url = "https://pypi.org/simple"
compile = true11. 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
Workflow 2: Production Project with Lock Files
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 systemDependency 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.txtVirtual 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 venv14. 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 space2. Increase Concurrent Downloads:
export UV_CONCURRENT_DOWNLOADS=1003. Use Lock Files:
# Lock files prevent re-resolving
uv pip sync requirements.txt # Faster than install4. Leverage Cache:
# Check cache stats
uv cache info
# Cache is automatic and shared across projects15. Best Practices & Tips
✅ DO
- Always use virtual environments
- Pin Python versions
- Use lock files for production
- Add .venv to .gitignore
- Use uvx for one-off commands
- Document your setup in README
- Use semantic versioning
uv venv # For each projectuv python pin 3.11uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt.venv/
__pycache__/
*.pycuvx black . # No installation neededpandas>=2.0.0,<3.0.0❌ DON'T
- Don't commit virtual environments - Add to .gitignore
- Don't use
sudowith 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 checkregularly
🎯 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
🚀 Getting Started Checklist
uv --version)📚 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! 🐍✨