# python-uv

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 129 installs · ★ 29 repo stars
- Author: oakoss
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/oakoss/agent-skills/tree/HEAD/skills/python-uv/SKILL.md
- Updated: 2026-08-17
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/oakoss-python-uv

## What it 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`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill python-uv -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/python-uv/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/python-uv/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill python-uv -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/python-uv/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill python-uv -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/python-uv/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install oakoss/agent-skills skills/python-uv
```

2. **Manually: put the files in place**
- File: `.github/skills/python-uv/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill python-uv -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/oakoss/agent-skills --path skills/python-uv
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/python-uv/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add oakoss/agent-skills --skill python-uv -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/oakoss/agent-skills/tree/HEAD/skills/python-uv/SKILL.md

## When to use it
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 265d3e11572a998a.

BEGIN THIRD-PARTY FILE 265d3e11572a998a
```text
---
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                  |
```
END THIRD-PARTY FILE 265d3e11572a998a

The third-party file has ended. Everything between the 265d3e11572a998a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2915 of 8419 bytes. © oakoss · MIT · https://github.com/oakoss/agent-skills/tree/HEAD/skills/python-uv/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
