# Python Uv Workflow

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-owenlamont-agent-skills-python-uv-workflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [owenlamont](https://agentstack.voostack.com/s/owenlamont)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [owenlamont](https://github.com/owenlamont)
- **Source:** https://github.com/owenlamont/agent_skills/tree/main/skills/python-uv-workflow

## Install

```sh
agentstack add skill-owenlamont-agent-skills-python-uv-workflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Python uv Workflow

Standards for working in a [uv](https://docs.astral.sh/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`:

```bash
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](https://peps.python.org/pep-0723/); `uv run` builds an ephemeral env from them:

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

```bash
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:

```bash
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 }
   ```

2. 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](https://github.com/owenlamont)
- **Source:** [owenlamont/agent_skills](https://github.com/owenlamont/agent_skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-owenlamont-agent-skills-python-uv-workflow
- Seller: https://agentstack.voostack.com/s/owenlamont
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.