python-uv-workflow

name	python-uv-workflow
description	Manage dependencies and run code in uv-based Python projects. Use when adding/upgrading dependencies, running Python code or scripts, bumping the project version, or bypassing the uv dependency cooldown for a security fix.

Python uv Workflow

Standards for working in a uv project. Prefer the uv CLI to manage dependencies and the project version — let it edit pyproject.toml and uv.lock rather than hand-editing them.

Dependencies and running code

Never activate a venv or call pip/python directly. Use the CLI so deps stay in sync across pyproject.toml and uv.lock:

uv add httpx        # add a dependency (uv add --dev for dev-only; uv remove to drop)
uv run pytest       # run a command in the project environment

Choosing dependencies

• Declare only packages your code imports directly as first-order dependencies — never lean on a transitive dependency.
• Keep linters, profilers, and locally-only tools (uvicorn, pytest plugins) in dev dependencies (uv add --dev), and keep heavy or specialised dependencies out of shared core packages so every consumer doesn't inherit them.
• Declare dev and other non-runtime dependencies in PEP 735 [dependency-groups] (what uv add --dev/--group write to), not [project.optional-dependencies].
• Don't add a dependency for a task the standard library handles, or one with no maintainer or recent release.

Updating and pinning

• Update one package at a time with uv lock --upgrade-package <pkg> rather than a blanket uv lock --upgrade, to keep lock churn reviewable.
• Verify the lockfile is current in CI with uv sync --locked (or uv lock --check).
• Pin only lower bounds in pyproject.toml (no upper bound without a documented reason), and pin Docker base images to a patch-level tag (e.g. python:3.13.1, not python:3.13).

Standalone scripts with inline dependencies

For a one-off script outside the project, declare deps inline with PEP 723; uv run builds an ephemeral env from them:

# /// script
# dependencies = ["httpx"]
# ///
import httpx

uv run script.py                  # runs in an ephemeral env with httpx
uv add --script script.py rich    # add a dep to the script's metadata

Bumping the project version

uv version reads or updates the version in pyproject.toml (and re-locks) — use it instead of hand-editing:

uv version                 # read current version
uv version --bump patch    # 0.1.0 -> 0.1.1  (also: minor, major)
uv version 2.0.0           # set an explicit version

--bump also accepts stable, alpha, beta, rc, post, dev (stackable, e.g. --bump minor --bump rc -> 1.1.0rc1). Add --dry-run to preview.

Bypassing the dependency cooldown for security fixes

The cooldown (exclude-newer under [tool.uv], e.g. "1 week") holds back freshly released versions. To take a newer version for a security fix, exempt only the affected package(s) — one of the few settings with no CLI equivalent, so edit pyproject.toml directly. A CLI-only --exclude-newer-package "<pkg>=false" is not durable: the next uv lock/uv sync re-resolves and strips it back out.

1. Add or extend the exemption table under [tool.uv] (keep existing entries):

   [tool.uv]
   exclude-newer = "1 week"
   exclude-newer-package = { cryptography = false }
   

2. Force the upgrade — editing alone won't move an already-locked package — then commit pyproject.toml and uv.lock:

   uv lock --upgrade-package cryptography
   

Remove the entry and re-lock once the version is older than the cooldown window.