UV pour Python

[!note] UV = future‑proof your Python workflow
UV is a rust‑powered Python package & project manager that handles Python versions, virtual environments, dependencies, lockfiles, scripts and tools—all insanely fast and unified.

🚀 What is uv?

uv (pronounced “you‑vee”) is a single tool that replaces pip, pipx, pyenv, pip-tools, venv, even poetry.
It supports cross-platform lockfiles, Python version management, script execution with embedded metadata, and legacy pip interface compatibility—written in Rust for speed and reliability.

🌟 Key Features

  • Python version manager: install and use specific versions or PyPy builds, entirely managed by uv. It auto-downloads missing versions as needed.
  • Automatic virtual environments: when you run uv run or uv sync in a project, uv will auto-create a .venv folder if none exists—no prompt needed.
  • Dependency management: uv add, uv remove, uv sync, uv lock vs. pip compile, pip sync, etc.—a universal lockfile (uv.lock) ensures consistent installs across platforms.
  • Script execution: run single-file scripts with inline dependency declarations and optional reproducibility via exclude-newer timestamps.
  • Pip-compatible CLI: uv pip install, uv pip freeze, uv pip compile, etc., work just like familiar pip tools—with massive performance gains.
  • Tool runner: commands like uvx (alias for uv tool run) let you run tools like ruff or pycowsay in isolated environments.

🛠️ Installation (quick-start)

On macOS/Linux:

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

On Windows (PowerShell):

1
irm https://astral.sh/uv/install.ps1 | iex

Self-contained and updatable with:

1
uv self update

You can also install via pip install uv or using pipx.

⚙️ Project Workflow

1. Initialize a new project

1
uv init

Creates pyproject.toml, .venv, and initial project structure. You can specify Python version:

1
uv init --python 3.12.4

2. Add dependencies

1
uv add fastapi uvicorn[standard]

Updates both pyproject.toml and environment—auto-creates .venv if needed.

3. Sync & lock

1
2
uv sync
uv lock

uv sync ensures .venv matches uv.lock; uv lock updates the lockfile.

4. Run commands

1
uv run -- flask run --port 8000

No need to activate .venv—uv run handles everything automatically.

✍️ Script Mode

For one-off scripts:

1
2
3
4
# example.py
# dependencies = ["requests"]
import requests
print(requests.__version__)

Run it with:

1
uv run example.py

You can also lock dependencies:

1
uv lock --script example.py

🔧 Pip-like Interface & Environments

Create a virtual environment:

1
uv venv

Or specify version:

1
uv venv --python 3.11

Install packages manually:

1
uv pip install numpy pandas

Requires .venv to exist (not auto-created in pip mode).

Lock & sync via pip interface:

1
2
uv pip compile requirements.in
uv pip sync requirements.txt

Or export to pylock.toml for standardization.

🧪 Full Workflow Example

1
2
3
4
5
6
mkdir myproj && cd myproj
uv init --python 3.12
uv add fastapi uvicorn
uv sync
uv lock
uv run python -c "import fastapi; print(fastapi.__version__)"

💡 Tips & Smart Tricks

  • uv python install 3.10 3.11 3.12 — install multiple Python versions
  • uv python pin 3.11 — write .python-version to pin interpreter
  • uv cache dir — view shared package cache location
  • uvx ruff — run ephemeral tools without global install

🚫 Limitations & Notes

  • .venv is created automatically — but not .env (for environment variables)
  • No automatic env var loading: use direnv, dotenv, etc.
  • Python binaries are not auto-symlinked — use uv python pin or link manually

🧠 Why switch?

  • Speed: 10× to 100× faster than pip/poetry/pip-tools
  • Unified: CLI handles venvs, Python installs, deps, lockfiles, scripts, tools
  • Reproducible: deterministic lockfiles, cache-first installs, .venv by default

📎 Further Reading

📅 Last updated: August 6, 2025