# Manage Python With Uv

> Manage Python projects and standalone scripts with uv, including setup, dependencies, execution, quality gates, locking, builds, and release preparation. Use for `uv run`, `uv add`, inline script metadata, packaging, or an explicitly requested publish workflow.

- Skill: `narumiruna/manage-python-with-uv` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add narumiruna/manage-python-with-uv`
- Raw SKILL.md: https://api.skillmd.com/api/skills/narumiruna/manage-python-with-uv/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: narumiruna (https://skillmd.com/u/narumiruna)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/narumiruna/manage-python-with-uv

---


# Python with uv

Use the repository's existing Python and verification choices first; use uv for dependency and execution operations unless a documented repository command wraps them.

## Choose the Mode

- **Project:** a `pyproject.toml`, lockfile, shared package, or local imports define an environment.
- **Standalone script:** one file or stdin should run without creating a project.
- Use `--no-project` only when the invocation must ignore the surrounding project and does not import its code.

## Project Workflow

1. Inspect `pyproject.toml`, lockfiles, repository instructions, and existing tools.
2. Initialize only genuinely new projects with `uv init`. Add or remove dependencies with `uv add` and `uv remove`; use `uv sync` to reconcile declared state.
3. Run Python and project tools through `uv run` or the repository's documented wrapper.
4. Preserve the established test, lint, type-check, coverage, and hook stack. For a new project with no stated requirements, add only tools that serve the requested quality bar.
5. Update and inspect the lockfile when dependency inputs change.
6. Run the narrow checks needed during iteration, then the repository's aggregate gate.

## Standalone Script Workflow

1. Use `uv run script.py` when no extra dependency is needed.
2. Use `uv run --with <dependency> script.py` for disposable dependencies.
3. Use `uv init --script` and `uv add --script` when dependencies or Python requirements should travel with a reusable script.
4. Put `--no-project` before the script name when isolation is intentional.
5. Read `references/scripts.md` only for inline metadata, stdin, shebang, locking, alternate indexes, or platform-specific patterns.

## Quality and Release

Use verification in this order: documented aggregate gate; the repository's configured hook runner; individual `uv run ...` commands when no aggregate gate exists or when narrowing a failure. Do not introduce or switch tools solely to run checks. Read `references/quality.md` for fallback patterns.

For release preparation:

1. Run the repository gate.
2. Build with `uv build --no-sources` so local source overrides cannot leak.
3. Inspect wheel and sdist contents.
4. Install and test the built wheel in a fresh uv-managed invocation.
5. Record the artifact names, checks, and lockfile state.

Publishing is a separate external write. Do not run `uv publish` based only on a request to build, package, prepare, or release. Require authorization for the exact package/version, repository or index, and artifacts; use secret-safe credentials and verify the resulting release. Read `references/packaging.md` for the authorized publish path.

## Invariants

- Do not use `pip install` to mutate a uv-managed project.
- Do not create `pyproject.toml` merely to run a one-file script.
- Do not use `--no-project` when local project imports are required.
- Treat `--with` as ephemeral; encode dependencies when reuse or reproducibility matters.
- Test the built or published artifact, not only the source checkout.