Manage Python projects and dependencies using uv. Use when setting up a Python project, adding/removing packages, running scripts in a uv-managed environment, creating virtual environments, or when any skill needs Python packages installed.
This skill defines the authoritative conventions for managing Python environments and dependencies with uv. All other skills that require Python should follow these conventions.
uv handles environments automatically. Prefer uv run over manually activating venvs. Prefer uv add over pip install. Let uv manage the lockfile (uv.lock) — never edit it by hand.
New project:
uv init my-project # creates pyproject.toml, .python-version, main.py
cd my-project
Existing project (first time):
uv sync # creates .venv and installs all dependencies from uv.lock
Pin Python version:
uv python pin 3.12 # writes .python-version — commit this file
Add a dependency:
uv add requests
uv add "fastapi>=0.100"
uv add --dev pytest ruff # dev-only dependencies
uv add --optional docs sphinx # optional group
Remove a dependency:
uv remove requests
Upgrade dependencies:
uv lock --upgrade-package requests # upgrade one
uv lock --upgrade # upgrade all
uv sync # apply changes
Check what's installed:
uv pip list
uv tree # show dependency tree
Always prefer uv run — it ensures the correct environment without activation:
uv run python script.py
uv run pytest
uv run ruff check .
uv run python -c "import sys; print(sys.version)"
Run a tool without installing it globally:
uvx ruff check . # runs ruff in an isolated env, no install needed
uvx httpie GET example.com
uv creates .venv in the project root automatically. Avoid manual activation when possible. When direct path access is needed:
.venv/bin/python # direct invocation (scripts, CI)
.venv/bin/pytest
Explicit venv creation (rarely needed):
uv venv # creates .venv in current directory
uv venv --python 3.11 # specific Python version
| File | Commit? | Notes |
|---|---|---|
pyproject.toml | Yes | dependency declarations |
uv.lock | Yes | reproducible installs |
.python-version | Yes | pins Python version |
.venv/ | No | always in .gitignore |
When a skill needs to run Python with packages:
# Check if project is already synced
uv sync --frozen # fast check — fails if lockfile is stale
# Install and run in one step
uv run --with requests python -c "import requests; ..."
# Run a script that needs specific packages
uv run --with pandas --with matplotlib python analyze.py
See uv documentation for full reference.