UV vs PIP: A Comprehensive Guide to Python Package Management
Published:
UV vs PIP: A Comprehensive Guide to Python Package Management
Overview
UV is a modern Python package manager designed to replace pip and streamline Python project management. While the core concepts are similar, UV introduces significant workflow changes that can feel unfamiliar to pip users.
Key Philosophy Differences:
- Pip: Manual environment management, explicit activation required.
- UV: Automatic environment management, project-centric approach.
Traditional Pip Workflow
1. Virtual Environment Creation and Management
# Create virtual environment
python -m venv .venv
# or
python3.11 -m venv .venv
# Activate environment (required before any work)
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
# Work in activated environment
(venv) $ pip install numpy pandas
(venv) $ python script.py
(venv) $ pip list
# Deactivate when done
deactivate
2. Dependency Management with Pip
# Install packages
pip install numpy pandas matplotlib
# Install from requirements.txt
pip install -r requirements.txt
# Save current dependencies
pip freeze > requirements.txt
# Install development dependencies
pip install pytest black flake8
# Uninstall packages
pip uninstall numpy
# List installed packages
pip list
pip show numpy
3. Project Structure with Pip
my-project/
├── .venv/ # Virtual environment
├── src/
│ └── myproject/
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── setup.py # Package configuration
└── README.md
4. Running Projects with Pip
# Always activate first
source .venv/bin/activate
# Then run your code
python script.py
pytest
# Don't forget to deactivate
deactivate
UV Workflow
1. Virtual Environment Creation and Management
# UV creates environments automatically when needed
uv sync # Creates venv if it doesn't exist
# No manual activation required for uv commands
uv run python script.py # Automatically uses .venv
# Optional: Manual activation still works
source .venv/bin/activate
# Now works without uv run
python script.py
2. Dependency Management with UV
# Add dependencies (updates pyproject.toml automatically)
uv add numpy pandas matplotlib
# Add development dependencies
uv add --dev pytest black ruff
# Add optional dependencies
uv add --optional plotting seaborn matplotlib
# Remove dependencies
uv remove numpy
# Sync environment with pyproject.toml
uv sync
# Install from pyproject.toml (like pip install -r requirements.txt)
uv sync
# List packages in current environment
uv pip list
3. Project Structure with UV
my-project/
├── .venv/ # Virtual environment (auto-created)
├── src/
│ └── myproject/
├── pyproject.toml # All project configuration
├── uv.lock # Locked dependency versions (auto-generated)
└── README.md
4. Running Projects with UV
# Method 1: Use uv run (no activation needed)
uv run python script.py
uv run python -m myproject
uv run pytest
# Method 2: Activate environment (traditional way)
source .venv/bin/activate
python script.py
pytest
# Method 3: Direct execution
.venv/bin/python script.py
Virtual Environment Management
Pip Virtual Environment Characteristics
A pip-created .venv/bin/ directory contains python, pip, the activate script, and installed package executables. pip is always available inside the environment.
# What's inside a pip-created .venv/bin/
ls .venv/bin/
source .venv/bin/activate
which pip # Points to .venv/bin/pip
pip install numpy
UV Virtual Environment Characteristics
A uv-created .venv/bin/ directory contains python, the activate script, and installed package executables, but notably, no pip by default.
# What's inside a uv-created .venv/bin/
ls .venv/bin/
# Pip is NOT available by default
source .venv/bin/activate
which pip # Points to system pip, not environment pip
python -m pip # Error: No module named pip
# UV pip commands work from anywhere
uv pip install numpy # Works inside or outside activated environment
uv pip list # Shows environment packages
Key Environment Differences
| Aspect | Pip Environment | UV Environment |
|---|---|---|
| Pip availability | ✔ Always included | ✗ Not included by default |
| Package installation | pip install | uv pip install or uv add |
| Activation required | ✔ For pip commands | ✗ For uv commands |
| Configuration file | requirements.txt | pyproject.toml |
| Lock file | Manual (pip freeze) | Automatic (uv.lock) |
Dependency Installation Methods
Pip Installation Methods
You must activate the environment first.
# Must activate environment first
source .venv/bin/activate
# Install individual packages
pip install numpy
pip install "numpy>=1.20.0"
# Install from requirements.txt
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Install in development mode
pip install -e .
# Install from git
pip install git+https://github.com/user/repo.git
UV Installation Methods
# Project dependencies (updates pyproject.toml)
uv add numpy # Latest version
uv add "numpy>=1.20.0" # Version constraint
uv add --dev pytest # Development dependency
# Direct environment installation (doesn't update pyproject.toml)
uv pip install numpy
# Install project in development mode
uv add -e .
# Install from git
uv add git+https://github.com/user/repo.git
# Sync from pyproject.toml
uv sync # Install all dependencies
uv sync --dev # Include dev dependencies
uv sync --no-dev # Exclude dev dependencies
Working in an Activated Environment
After activating a UV environment:
uvcommands likeuv addanduv pip installstill work.- The traditional
pip installwill fail because thepipmodule is not installed. - You can add
pipas a development dependency to the environment to makepip installwork.
# After activating UV environment
source .venv/bin/activate
# These UV commands still work
uv add matplotlib # Works, updates pyproject.toml
uv pip install ipython # Works, temporary installation
# Traditional pip doesn't work
pip install numpy # X Error: no pip module
# But it might work if pip was added
uv add --dev pip # Add pip to environment
source .venv/bin/activate
pip install numpy # Now works
Project Running Approaches
Pip Project Running
Running projects with Pip always requires activating the environment first.
# Always require activation
source .venv/bin/activate
# Then run normally
python script.py
python -m mypackage
pytest
jupyter notebook
# Remember to deactivate
deactivate
UV Project Running
Approach 1: UV Run (Recommended for Commands) This method does not require activation as it auto-manages the environment.
# No activation needed, auto-manages environment
uv run python script.py
uv run python -m mypackage
uv run pytest
uv run jupyter notebook
uv run mycommand # For project with script entry points
Approach 2: Traditional Activation This works exactly like pip.
# Works exactly like pip
source .venv/bin/activate
# Run normally
python script.py
mycommand
pytest
deactivate
Approach 3: Direct Execution You can run scripts by providing the direct path to the Python executable in the virtual environment.
# No activation, direct path
.venv/bin/python script.py
.venv/bin/mycommand # If installed as script
Key Differences Summary
Configuration Files
| Aspect | Pip | UV |
|---|---|---|
| Dependency list | requirements.txt | pyproject.toml |
| Lock file | Manual (pip freeze) | uv.lock (automatic) |
| Dev dependencies | requirements-dev.txt | pyproject.toml dev group |
| Project metadata | setup.py/setup.cfg | pyproject.toml |
Command Equivalents
| Pip Command | UV Equivalent | Notes |
|---|---|---|
pip install numpy | uv add numpy | UV updates pyproject.toml |
pip install -r requirements.txt | uv sync | UV uses pyproject.toml |
pip list | uv pip list | Note the extra “pip” |
pip uninstall numpy | uv remove numpy | UV updates pyproject.toml |
pip freeze > requirements.txt | Auto-generated uv.lock | Automatic in UV |
python script.py (in venv) | uv run python script.py | No activation needed |
Environment Management
| Aspect | Pip | UV |
|---|---|---|
| Creation | python -m venv .venv | uv sync (automatic) |
| Activation | Always required | Optional |
| Package tools | pip included | uv pip commands |
| Isolation | Manual management | Automatic management |
Conclusion
UV represents a significant evolution in Python package management.
Advantages:
- Automatic environment management
- Integrated project configuration
- Faster dependency resolution
- Modern tooling approach
- Consistent cross-platform behavior
Learning Curve:
- Requires a mental model shift from
pip - New command patterns
- Different environment structure
- Project-centric vs. environment-centric thinking
The transition from pip to uv is ultimately about embracing automation and project-centric workflows while maintaining the flexibility to work in traditional ways when needed. The key insight is that uv environments work just like pip environments once activated; the main difference is in how you manage them.
Recommendation: Start with a mixed approach. Use uv for dependency management but keep familiar activation patterns until you’re comfortable with the full uv workflow.