Python Uv Workflow

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 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 "=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):

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

1. Force the upgrade — editing alone won't move an already-locked package — then commit

pyproject.toml and uv.lock:

``bash uv lock --upgrade-package cryptography ``

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: owenlamont
• Source: owenlamont/agent_skills
• License: MIT

Install and usage instructions live in the source repository linked above.