Fast Python environment management with uv (10-100x faster than pip). Triggers on: uv, venv, pip, pyproject, python environment, install package, dependencies.
Fast Python environment management with uv. Prefer the uv project workflow
(uv add / uv sync / uv run) over the uv pip compatibility layer — it
manages pyproject.toml + a lockfile for you and is reproducible.
| Task | Command |
|---|---|
| Start a project | uv init <name> (app) · uv init --package <name> (installable, src/ layout) |
| Add dependency | uv add httpx |
| Add dev dependency | uv add --dev pytest ruff |
| Remove dependency | uv remove httpx |
| Sync env from lockfile | uv sync |
| Run in project env | uv run pytest |
| Update lockfile | uv lock |
| Install a CLI tool | uv tool install ruff · one-shot: uvx ruff |
| Install a Python | uv python install 3.12 |
# Application (flat layout, no package build)
uv init myapp
# Installable package (src/ layout — separate tests/ that import by name)
uv init --package wordtools
# → src/wordtools/__init__.py, pyproject.toml with build-system
uv init creates pyproject.toml, pins a Python version, and prepares the
project for uv add / uv sync. The --package (src) layout is preferred for
anything with a test suite or that you intend to ship.
# Add runtime deps (writes to [project.dependencies] + updates the lockfile)
uv add "httpx>=0.25" pydantic
# Add dev-only deps (writes to the dev dependency-group)
uv add --dev pytest ruff mypy
# Add with extras
uv add "fastapi[standard]"
# Remove
uv remove httpx
# Install everything from pyproject + uv.lock into .venv (reproducible)
uv sync
# Refresh the lockfile (e.g. after manual pyproject edits)
uv lock
uv creates and manages .venv automatically — you rarely activate it; just
prefix commands with uv run.
uv run python script.py # run a script in the project env
uv run pytest # run a tool from the dev group
uv run -- ruff check . # `--` ends uv flag parsing
Never call bare python / pytest / ruff in a uv project — they may resolve
to a different interpreter. Always uv run.
uv tool install ruff # persistent, isolated, on PATH
uv tool upgrade ruff
uvx ruff check . # ephemeral one-shot run, nothing installed
Use uv tool / uvx for developer CLIs (ruff, pre-commit, httpie). Use
uv add only for things your code imports.
uv python install 3.12 # download a managed interpreter
uv python list # show available + installed
uv init --python 3.12 app # pin a project to a version
3.13 is the current stable release (free-threading and JIT, both opt-in); 3.11+
is a sensible floor for new projects (TaskGroup, Self, faster interpreter).
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"httpx>=0.25",
"pydantic>=2.0",
]
# Dev deps live here; `uv add --dev <pkg>` manages this group.
[dependency-groups]
dev = [
"pytest>=8.0",
"ruff>=0.4",
"mypy>=1.10",
]
uv pip) — last resortuv pip mirrors pip's interface for environments uv doesn't manage (a hand-made
venv, a legacy requirements.txt, CI that isn't uv-native). It does not
update pyproject.toml or the lockfile — prefer uv add / uv sync whenever
you control the project.
uv venv # bare venv (no project)
uv pip install -r requirements.txt # legacy requirements file
uv pip install -e . # editable install into an unmanaged venv
uv pip compile requirements.in -o requirements.txt # pin a requirements.txt
| Issue | Solution |
|---|---|
| "No Python found" | uv python install 3.12 |
| Pin project Python | uv init --python 3.12 or edit requires-python |
| Lock/resolve conflict | uv lock --resolution=lowest-direct to probe, then loosen bounds |
| Stale env after pull | uv sync |
| Cache issues | uv cache clean |
uv add / uv remove / uv sync for project dependencies (not uv pip install)uv run to execute anything inside the project envuv tool install / uvx for standalone developer CLIsuv pip only for environments uv doesn't manageFor detailed patterns, load:
./references/pyproject-patterns.md - Full pyproject.toml examples, tool configs./references/dependency-management.md - Lock files, workspaces, private packages./references/publishing.md - PyPI publishing, versioning, CI/CDThis is a foundation skill with no prerequisites.
Build on this skill:
python-typing-ops - Type hints for projectspython-pytest-ops - Testing infrastructurepython-fastapi-ops - Web API development
