uv Cheatsheet — The All-in-One Python Package Manager
What is uv?
uv is an extremely fast Python package and project manager written in Rust by Astral (the creators of Ruff and ty). It is designed as a single binary that replaces pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more — while being 10–100× faster.
uv achieves this through parallel downloads, an optimized PubGrub dependency resolver, a global cache for deduplication, and zero-copy optimizations. It works on macOS, Linux, and Windows and can be installed without Rust or Python.
This cheatsheet is split into focused sub-articles so you can bookmark what you need:
| Section | What it covers |
|---|---|
| Installation | Installing, updating, uninstalling uv on openSUSE / Linux, shell completion |
| Python Management | Installing, listing, pinning, upgrading Python versions |
| Projects | uv init, project structure, pyproject.toml, running and syncing |
| Dependencies | Adding, removing, upgrading packages; extras; dependency groups; sources |
| Scripts & Tools | Inline script metadata, uv run, uvx, installing CLI tools |
| Workspaces | Monorepo setup, workspace members, shared lockfile |
| pip Compatibility | Drop-in uv pip commands, venv, compile, sync |
| Configuration & Cache | pyproject.toml settings, uv.toml, environment variables, cache management |
| Building & Publishing | uv build, uv publish, the uv build backend |
Quick-Start (30 seconds)
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Create a project
uv init my-project && cd my-project
# Add a dependency
uv add requests
# Run your code
uv run main.pyThat’s it. uv automatically downloads a suitable Python version, creates a virtual environment, resolves dependencies, generates a lockfile, and runs your code.
Key Concepts
Global cache — uv deduplicates packages across all your projects in a single cache directory (~/.cache/uv on Linux). This saves disk space and makes installs near-instant when packages are already cached.
Lockfile (uv.lock) — A cross-platform, human-readable TOML file containing exact resolved versions. It is managed by uv and should not be edited manually. Commit it to version control for reproducible builds.
Managed Python — uv can download and manage Python installations itself (from Astral’s python-build-standalone project). These are called “managed” Python versions, as opposed to “system” Python versions already on your machine.
pyproject.toml — The single source of truth for your project’s metadata, dependencies, and uv-specific configuration (under [tool.uv]).