Guide for using uv - an extremely fast Python package and project manager written in Rust. Use when installing Python, managing virtual environments, adding dependencies, running scripts, building packages, or working with pyproject.toml. Replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv.
Guide for using uv - an extremely fast Python package and project manager written in Rust. Use when installing Python, managing virtual environments, adding dependencies, running scripts, building packages, or working with pyproject.toml. Replaces pip, pip-tools, pipx, poetry, pyenv, twine, and virtualenv.
uv-version
>=0.5.x
updated
2025-01-15T00:00:00.000Z
uv Skill
Extremely fast Python package and project manager by Astral (Ruff creators).
Overview
uv is a single tool that replaces:
pip/pip-tools - Package installation and dependency resolution
virtualenv/venv - Virtual environment creation
pyenv - Python version management
pipx - Tool installation and execution
poetry/pdm - Project and dependency management
twine - Package publishing
Key Features:
10-100x faster than pip
Universal lockfile (uv.lock) for reproducible builds
Automatic Python version management
Built-in tool execution (uvx)
PEP 723 inline script dependencies
Drop-in pip compatibility
Quick Reference
Task
Command
New project
uv init
New library
uv init --lib
Add package
uv add <pkg>
Add dev dependency
uv add --dev <pkg>
Remove package
uv remove <pkg>
Install all deps
uv sync
Install (CI/prod)
uv sync --locked
Run command
uv run <cmd>
Run tool (no install)
uvx <tool>
Install Python
uv python install 3.12
Pin Python version
uv python pin 3.12
Update all deps
uv lock --upgrade
Update one package
uv lock --upgrade-package <pkg>
Show dep tree
uv tree
Build package
uv build
Publish to PyPI
uv publish
Quick Start
Installation
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# Via pip/pipx
pipx install uv
pip install uv
# Homebrew
brew install uv
# Run in project environment
uv run python script.py
uv run pytest
uv run flask run
# Run with temporary dependency
uv run --with pandas script.py
# Run tools without installing (uvx)
uvx ruff check .
uvx black --check .
uvx --from httpie http https://example.com
5. Python Version Management
# Install Python versions
uv python install # Latest version
uv python install 3.12 # Specific version
uv python install 3.11 3.12 3.13 # Multiple# List versions
uv python list
uv python list --only-installed
# Pin version
uv python pin 3.12 # Project (.python-version)
uv python pin --global 3.12 # User default# Find Python
uv python find
uv python find ">=3.11"
6. Virtual Environments
# Create (usually automatic)
uv venv # Creates .venv
uv venv my-env # Custom name
uv venv --python 3.12 # Specific Python# Activate (optional - uv run auto-detects)source .venv/bin/activate # macOS/Linux
.venv\Scripts\activate # Windows
# Create and enter project
uv init my-project
cd my-project
# Add dependencies
uv add flask sqlalchemy
uv add --dev pytest ruff mypy
# Run application
uv run flask run
# Run tests
uv run pytest
Hybrid approach: Use conda for system dependencies, uv for Python packages:
# Conda for non-Python deps
conda create -n myenv python=3.12 cudatoolkit
# Activate conda env, then use uv
conda activate myenv
export UV_SYSTEM_PYTHON=1
uv pip install -r requirements.txt
Common Pitfalls
1. Forgetting --locked in CI/Production
# Wrong - may update lockfile unexpectedly
uv sync# Correct - fails if lockfile is outdated (reproducible builds)
uv sync --locked
2. Mixing uv and pip Commands
# Don't do this - breaks uv's dependency tracking
pip install some-package
source .venv/bin/activate && pip install another-package
# Do this instead - uv tracks all dependencies
uv add some-package
# Or use uv's pip interface if needed
uv pip install some-package
3. Not Committing uv.lock
The uv.lock file must be committed to version control for
reproducible builds. Without it, environments may resolve differently.
# .gitignore - DON'T ignore uv.lock
.venv/
__pycache__/
# uv.lock <-- DO NOT ADD THIS LINE
4. Running Commands Outside Project Environment
# Wrong - uses system Python, not project environment
python script.py
pytest
# Correct - runs within project's virtual environment
uv run python script.py
uv run pytest
5. Editing uv.lock Manually
Never edit uv.lock by hand. It's auto-generated and managed by uv.
# To update a specific package
uv lock --upgrade-package requests
# To upgrade all packages
uv lock --upgrade
# To regenerate from scratchrm uv.lock && uv lock
6. Using --frozen When You Mean --locked
# --frozen: Don't update lockfile, but don't verify it either
uv sync --frozen
# --locked: Verify lockfile matches pyproject.toml (use this in CI)
uv sync --locked
Troubleshooting
Common Issues
Issue
Cause
Solution
No pyproject.toml
Wrong directory
cd to root or uv init
Package not found
Wrong index/typo
Check name, try --index
Lockfile outdated
pyproject changed
Run uv lock
Resolver conflict
Version conflicts
Try uv lock --upgrade
Python mismatch
Not installed
uv python install 3.12
Build failures
Missing deps
Try --no-build-isolation
Hash mismatch
Corrupted cache
uv cache clean
Slow first run
Cold cache
Normal, uses cache after
Debug Commands
# Check current environment
uv python find
uv pip list
# Verbose output
uv sync -v
uv sync -vv # More verbose# Check lockfile status
uv lock --check
# Clear cache
uv cache clean
uv cache prune --ci # For CI environments
uv pip install -e . works but doesn't write the editable install to uv.lock — the lockfile is wrong on next uv sync. Use uv add --editable instead.
uv sync --frozen fails if dependencies upgraded outside the lock — won't auto-update; emit a clear error message but blocks CI until you uv lock --upgrade-package <name>.
uv venv creates .venv in CWD — missing --directory after cd puts the venv in the wrong place. Pin with UV_PROJECT_ENVIRONMENT env var or absolute paths in scripts.
uv tool install and uv pip install go to DIFFERENT environments — uv tools are isolated per-tool; pip-installed packages aren't visible to uv-installed tools.
Pin via ==X.Y.Z in pyproject.toml doesn't lock; only uv.lock does — dependencies = ["foo==1.2.3"] allows uv to pick any compatible 1.2.3, including yanked versions.
