Skip to main content
skill CX Codex

python-uv · oakoss — Claude Code skill: what it does, how to install

python-uv teaches coding agents to manage Python projects with uv: initialization, dependencies, lockfiles, workspaces, and packaging. Useful when migrating from pip and poetry workflows.

MIT 129 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill python-uv -a claude-code
Open on GitHub

What python-uv does

This skill equips coding agents with direct patterns for managing Python projects using uv. Instead of mixing pip, poetry, and virtualenv, the model relies on unified commands like uv init, uv add, and uv sync. It enforces proper pyproject.toml configuration, lockfile maintenance with uv.lock, and transient tool runs via uvx.

The instructions cover multi-package monorepo workspaces, inline script metadata under PEP 723, and publishing packages to PyPI. They prevent frequent mistakes like committing the .venv folder or activating environments manually before running commands. uv will not fit conda environments that rely on binary system packages or legacy workflows tied strictly to setup.py.

What it helps with

  • initialize Python apps or typed libraries with pyproject.toml
  • manage dependencies and pin exact versions in uv.lock
  • configure CI check steps using uv sync --locked
  • run standalone scripts with inline PEP 723 dependencies via uv run

Example prompts for the agent

  • Initialize a new Python library using uv with type hint support
  • Add pytest to dev dependencies and update the lockfile
  • Prepare a Dockerfile that installs dependencies using uv sync --frozen

How to install python-uv

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill python-uv -a claude-code

2Manually: put the files in place

~/.claude/skills/python-uv/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/python-uv/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about python-uv

How to install python-uv in Claude Code?

Run npx skills add oakoss/agent-skills --skill python-uv -a claude-code in your terminal. The skill file will be placed in ~/.claude/skills/python-uv/SKILL.md.

What does python-uv do?

It gives the agent guidelines and command references for uv, preventing common pitfalls such as manual virtual environment activation or committing .venv.

When should python-uv not be used?

Avoid using it for non-Python repositories, conda-managed scientific setups with system binary dependencies, or legacy packages locked to setup.py.

Source text

SKILL.md · MIT
---
name: python-uv
description: |
  Modern Python development with uv, the fast Python package and project manager. Covers project management (uv init, uv add, uv sync, uv lock), virtual environments, Python version management (uv python install/pin), script runners (uv run), tool management (uvx), workspace support for monorepos, and publishing to PyPI. Includes Python patterns for FastAPI, Pydantic, async/await, type checking, pytest, structlog, and CLI tools.

  Use when initializing Python projects, managing dependencies with uv, configuring pyproject.toml, setting up virtual environments, running scripts, managing Python versions, building monorepos with workspaces, containerizing Python apps, or writing modern Python with type hints.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://docs.astral.sh/uv/'
user-invocable: false
---

# Python uv

## Overview

uv is an extremely fast Python package and project manager written in Rust, designed to replace pip, pip-tools, pipx, poetry, pyenv, and virtualenv. It provides unified project management, dependency resolution, Python version management, and tool execution with 10-100x speed improvements over traditional tools.

**Key capabilities:** Project initialization, dependency locking and syncing, Python version management, PEP 723 inline script dependencies, ephemeral tool execution via `uvx`, monorepo workspaces with shared lockfiles, and package building/publishing.

**When to use:** Python project initialization, dependency management, virtual environments, Python version pinning, running scripts with inline dependencies, monorepo workspaces, tool execution, publishing packages.

**When NOT to use:** Non-Python projects, conda-managed scientific computing environments with system-level binary dependencies, projects locked to legacy `setup.py`-only workflows.

## Quick Reference

| Pattern              | Command / API                         | Key Points                                     |
| -------------------- | ------------------------------------- | ---------------------------------------------- |
| Init project         | `uv init`                             | Creates `pyproject.toml` and `.python-version` |
| Init library         | `uv init --lib`                       | Creates `src/` layout with `py.typed`          |
| Init script          | `uv init --script example.py`         | PEP 723 inline metadata script                 |
| Add dependency       | `uv add requests`                     | Adds to `pyproject.toml`, updates lockfile     |
| Add dev dependency   | `uv add --dev pytest`                 | Adds to `[dependency-groups]` dev group        |
| Add group dependency | `uv add --group docs mkdocs`          | Custom dependency groups                       |
| Add optional         | `uv add --optional postgres psycopg`  | Optional extras for libraries                  |
| Remove dependency    | `uv remove requests`                  | Removes from `pyproject.toml` and lockfile     |
| Lock dependencies    | `uv lock`                             | Creates/updates `uv.lock`                      |
| Upgrade in lockfile  | `uv lock --upgrade-package requests`  | Targeted dependency upgrade                    |
| Sync environment     | `uv sync`                             | Installs locked dependencies into `.venv`      |
| Sync for CI          | `uv sync --locked`                    | Fails if lockfile is stale                     |
| Sync frozen          | `uv sync --frozen`                    | Skips lockfile verification                    |
| Run command          | `uv run python app.py`                | Runs in project virtual environment            |
| Run script           | `uv run script.py`                    | Supports PEP 723 inline dependencies           |
| Run in package       | `uv run --package api pytest`         | Workspace-specific execution                   |
| Install Python       | `uv python install 3.13`              | Downloads and manages Python versions          |
| Pin Python           | `uv python pin 3.12`                  | Writes `.python-version` file                  |
| List Pythons         | `uv python list`                      | Shows available and installed versions         |
| Run tool             | `uvx ruff check .`                    | Ephemeral tool execution                       |
| Tool with plugins    | `uvx --with mkdocs-material mkdocs`   | Ephemeral tool with extra packages             |
| Install tool         | `uv tool install ruff`                | Persistent global tool install                 |
| Workspace            | `[tool.uv.workspace]`                 | Monorepo multi-package support                 |
| Build package        | `uv build`                            | Creates sdist and wheel in `dist/`             |
| Publish              | `uv publish`                          | Uploads to PyPI with trusted publishing        |
| Export deps          | `uv export --format requirements-txt` | Generate requirements.txt from lockfile        |

## Common Mistakes

| Mistake                                     | Correct Pattern                                                          |
| ------------------------------------------- | ------------------------------------------------------------------------ |
| Using `pip install` inside uv project       | `uv add` to manage via `pyproject.toml`                                  |
| Activating venv manually before `uv run`    | `uv run` handles venv activation automatically                           |
| Committing `.venv/` to version control      | Add `.venv/` to `.gitignore`, commit `uv.lock`                           |
| Not committing `uv.lock`                    | Always commit `uv.lock` for reproducible builds                          |
| Using `uv sync` without `--locked` in CI    | `uv sync --locked` ensures lockfile matches `pyproject.toml`             |
| Running `uv lock --upgrade` routinely       | Only upgrade intentionally, use `--upgrade-package` for targeted updates |
| Mixing `pip` and `uv` dependency management | Choose one tool for the project consistently                             |
| Using `uv pip install` for project deps     | Use `uv add`/`uv sync` for managed projects                              |
| Forgetting `--frozen` for Docker builds     | `uv sync --frozen` skips lockfile verification for faster builds         |
| Creating venv manually in uv project        | `uv sync` creates and manages `.venv` automatically                      |
| Using `setup.py` for new projects           | Use `pyproject.toml` with a modern build backend                         |
| Not using `py.typed` in libraries           | `uv init --lib` includes it, required for typed packages                 |

## Delegation

- **Project scaffolding**: Use `Explore` agent
- **Dependency audit**: Use `Task` agent
- **Code review**: Delegate to `code-reviewer` agent

> If the `docker` skill is available, delegate containerization patterns to it.
> If the `github-actions` skill is available, delegate CI/CD pipeline configuration to it.
> If the `api-testing` skill is available, delegate API testing patterns to it.
> If the `sentry-setup-logging` skill is available, delegate error monitoring setup to it.
> If the `pino-logging` skill is available, delegate Node.js logging patterns to it (Python equivalent covered here with structlog).

## References

- [Project management and pyproject.toml configuration](references/project-management.md)
- [Dependency management, lockfiles, and groups](references/dependency-management.md)
- [Python version management and virtual environments](references/python-environments.md)
- [Scripts, inline dependencies, and tool management](references/scripts-and-tools.md)
- [Workspace support for monorepos](references/workspaces.md)
- [FastAPI web framework patterns](references/fastapi-patterns.md)
- [Pydantic validation and data modeling](references/pydantic-validation.md)
- [Async patterns with asyncio](references/async-patterns.md)
- [Type checking with mypy and pyright](references/type-checking.md)
- [Testing with pytest](references/testing-patterns.md)
- [Logging with structlog](references/structlog-logging.md)
- [CLI applications with typer](references/cli-applications.md)
- [Docker integration and publishing](references/docker-and-publishing.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Programming languages →

python-uv by other authors comes first.

python-uv Mindrally python-uv makes the agent manage Python packages through uv only, no pip or poetry. Useful when the project already runs on uv or when environments keep drifting apart. CX Codex +1 1,000installs setup-python-env reflex-dev setup-python-env is a Claude Code skill that creates a Python virtual environment and installs Reflex when starting a project or when the agent finds no .venv directory. CX Codex +1 794installs python-pro Seth Hobson python-pro — a subagent for modern Python 3.12+ development, async code, testing, APIs, and performance work. Use it when a project needs deeper Python guidance. CX Codex 11,689installs python-scaffold Seth Hobson python-scaffold is a Claude Code command that scaffolds FastAPI, Django, library, and CLI projects. It builds the project layout and development configuration from a request. CX Codex +1 ★ 42,780repo stars uv astral-sh Skill for Claude Code and Codex guides the assistant in using the uv package manager. Activates when handling Python scripts, dependencies, lockfiles, and tools. CX Codex +1 5,300installs python-pypi-package-builder official github The python-pypi-package-builder skill guides Python package creation, testing, versioning, and PyPI publishing. Use it for libraries, SDKs, CLI tools, and framework plugins. CX Codex +1 943installs modern-python trailofbits modern-python configures Python projects with a modern tooling stack: uv for dependency management, ruff for linting and formatting, ty for type checking. Use when starting new projects, writing scripts, or migrating from legacy tools. CX Codex +1 9,700installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open