Introduction
Python’s tooling has been fragmented for years: pyenv for versions, venv for environments, pip for packages, poetry/pipenv for lockfiles. uv replaces all of them — one tool, written in Rust, 10-100x faster.
In 2026, uv is the default for new Python projects. This post gets you productive in 10 minutes.
What is uv?
uv is a Python package manager from Astral (creators of Ruff). It:
- Installs Python versions (
uv python install 3.12) - Creates virtual environments (
uv venv) - Installs packages (
uv add,uv sync) - Manages lockfiles (
uv.lock) - Runs scripts (
uv run) - Publishes packages (
uv publish)
One binary, no Python required to install it.
Install
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or via pip (if you must)
pip install uv
Verify: uv --version
Step 1: Create a project
uv init my-project
cd my-project
Creates:
my-project/
├── pyproject.toml
├── README.md
└── .python-version # pins Python version
Step 2: Add dependencies
uv add requests pandas streamlit
uv add --dev pytest ruff mypy
This updates pyproject.toml and creates uv.lock (reproducible lockfile). No requirements.txt needed.
Step 3: Run code
uv run python main.py
uv run pytest
uv run streamlit run app.py
uv run automatically creates the venv, installs deps, and runs. No manual source .venv/bin/activate.
Step 4: Pin Python version
uv python install 3.12
uv python pin 3.12
Creates .python-version. Anyone cloning the repo gets the same Python version automatically.
Step 5: Sync (for collaborators)
git clone <repo>
cd <repo>
uv sync # creates venv, installs everything from uv.lock
Deterministic, fast (~1-2s for most projects).
Step 6: Scripts with inline deps
uv can run single-file scripts with their own dependencies:
# script.py
# /// script
# dependencies = ["requests", "rich"]
# ///
import requests
from rich import print
r = requests.get("https://api.github.com")
print(r.json())
Run: uv run script.py — uv creates a temp venv, installs deps, runs. No project needed.
Step 7: Tool management (like pipx)
uv tool install ruff
uv tool install black
uv tool run ruff check .
uv tool installs CLI tools in isolated environments (like pipx), but faster.
uv vs the old stack
| Task | Old way | uv way |
|---|---|---|
| Install Python | pyenv | uv python install |
| Create venv | python -m venv |
uv venv (auto) |
| Install packages | pip install |
uv add |
| Lockfile | pip freeze / poetry lock | uv lock (auto) |
| Run code | source .venv/bin/activate && python |
uv run python |
| Install CLI tools | pipx | uv tool install |
| Speed | Slow (pip) | 10-100x faster |
Migrating from pip/poetry
# From requirements.txt
uv add -r requirements.txt
# From poetry
uv init # then manually copy deps from pyproject.toml
# or use: uv add $(poetry export --without-hashes -f requirements.txt | grep -v '^#' | cut -d= -f1)
# From pipenv
# Copy [packages] from Pipfile to pyproject.toml [project.dependencies]
Common workflows
New project from scratch
uv init my-app
cd my-app
uv add streamlit pandas
uv add --dev pytest ruff
uv run streamlit run app.py
Existing project
cd existing-project
uv init # if no pyproject.toml
uv add -r requirements.txt
uv sync
CI/CD
# GitHub Actions
- uses: astral-sh/setup-uv@v4
- run: uv sync
- run: uv run pytest
setup-uv is 10x faster than setup-python + pip install.
Common mistakes
- Mixing pip and uv — don’t
pip installin a uv project. Useuv addoruv pip install. - Forgetting
uv.lock— commit it. It ensures reproducibility. - Using
uv pip installfor everything —uv addis preferred for project deps (updates pyproject.toml + lockfile). - Not pinning Python — add
.python-versionto git. - Ignoring the cache — uv caches aggressively.
uv cache cleanif things go weird.
Key Concepts
- uv = one tool for Python versions, venvs, packages, lockfiles
uv add= add dependency (updates pyproject.toml + uv.lock)uv run= run in the project’s venv (auto-created)uv sync= install from lockfile (deterministic)uv tool= install CLI tools (like pipx)- Inline scripts = single-file deps with
# /// script
What to Try Next
- Migrate your Streamlit app to uv — faster CI/CD builds.
- Use
uv runin your FastAPI backend. - Combine with pytest for fast test runs.
- Use inline script deps for one-off automation scripts.
FAQ
uv vs poetry?
Poetry is slower, requires Python to install, and has a more complex lockfile format. uv is 10-100x faster, standalone binary, and uses standard pyproject.toml. For new projects, uv. For existing Poetry projects, migration is straightforward.
uv vs conda?
Conda manages non-Python dependencies (C libraries, CUDA). uv is Python-only. If you need conda’s system packages (e.g., for ML with CUDA), keep conda. For pure Python, uv wins.
Is uv production-ready?
Yes — it’s used by major companies and has a stable API. Astral (creators of Ruff, used by millions) backs it. The 1.0 release is stable. Many projects have migrated.<|end|><|start|>write to=assistant<|channel|>analysis<|message|>Created file successfully: src/content/posts/python-uv-modern-tooling.md