Setting Python Versions
Create venv with specific Python version
uv venv .venv --python 3.11.6
Pin Python version for project
uv python pin 3.12
Set global default Python version
uv python pin --global 3.12
Run script with specific version (one-off)
uv run --python 3.12 -- python my_script.py
Working with Existing Projects
Initialize UV in existing project
uv init
Create and activate virtual environment
uv venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
Install dependencies from requirements.txt
uv pip install -r requirements.txt
# or
uv add -r requirements.txt
Sync dependencies (pyproject.toml)
uv sync
Package Management
List installed packages
uv pip list
Add new package
uv add package-name
Add dev dependency
uv add --dev package-name
Remove package
uv remove package-name
Update packages
uv lock --upgrade
uv sync
Python Version Management
Install Python version
uv python install 3.12
List available Python versions
uv python list
List installed Python versions
uv python list --only-installed
Running Commands
Run command in venv without activating
uv run python script.py
uv run pytest
uv run uvicorn main:app --reload
Create new project from scratch
uv init my-project
cd my-project
uv add requests pandas numpy
Quick Reference
| Task | Command |
|---|
| New project | uv init project-name |
| Add package | uv add package-name |
| Install deps | uv sync |
| Run script | uv run python script.py |
| Pin Python | uv python pin 3.12 |
| List packages | uv pip list |
| Update all | uv lock --upgrade && uv sync |
Others
# Create isolated tool environments
uv tool install ruff
uv tool install black
# Export requirements.txt from pyproject.toml
uv pip compile pyproject.toml -o requirements.txt