Skip to content
uv

uv Skill

Astral's official skill that teaches coding agents to use uv for Python scripts, projects, tools and type checking, and to migrate pip, pipx and pyenv commands to their uv equivalents.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from astral-sh/agent-plugins.

$ npx skills add astral-sh/agent-plugins --skill uv

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/uv/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/astral-sh/agent-plugins.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/plugins/astral/skills/uv ~/.claude/skills/uv

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/uv/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Detects uv projects from uv.lock and uv-generated requirements files
  • Workflows for scripts, projects, tools and the legacy pip interface
  • Type checking with uv check and ty, including PEP 723 scripts
  • Migration table from pyenv, pipx, pip, pip-tools and virtualenv
  • Bad-versus-good patterns: no pip install, no bare python, no manual venvs
  • Safety note on running unknown tools with uvx

uv is the official agent skill for uv, Astral's fast Python package and project manager, published by Astral in its astral-sh/agent-plugins repository. It tells a coding agent to use uv for Python work whenever a project shows signs of it, such as a uv.lock file or requirements files generated by uv, and to stay out of projects managed by Poetry or PDM.

The skill splits the work into workflows. Single-file scripts run with uv run, with extra packages via --with or inline dependencies added by uv add --script. Projects with a pyproject.toml use uv init, uv add, uv remove, uv sync (or --locked) and uv run, including running on a specific Python version. Project tools run through uv run so they use locked versions, while standalone tools run through uvx, with a warning that uvx installs from PyPI by name and should only run well-known tools. uv check type checks a project or a PEP 723 script with Astral's ty. The pip interface is reserved for legacy requirements.txt workflows.

A migration table maps pyenv, pipx, pip, pip-tools and virtualenv commands to their uv equivalents, and a set of "bad and good" patterns stops the agent from running pip install, calling python directly or activating virtual environments by hand in a uv project. It ends by pointing to uv's llms.txt documentation. The repository is Apache-2.0 licensed.

SKILL.md

The instructions your agent loads, as published by Astral.

SKILL.md
name
uv
description
Guide for using uv, the Python package and project manager. Use this when working with Python projects, scripts, packages, or tools.

uv

uv is an extremely fast Python package and project manager. It replaces pip,
pip-tools, pipx, pyenv, virtualenv, poetry, etc.

When to use uv

Always use uv for Python work, especially if you see:

  • The uv.lock file
  • uv headers in requirements* files, e.g., "This file was autogenerated by uv"

Don't use uv in projects managed by other tools:

  • Poetry projects (identifiable by poetry.lock file)
  • PDM projects (identifiable by pdm.lock file)
Choosing the right workflow
Scripts

Use when: Running single Python files and standalone scripts.

Key commands:

uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script
Projects

Use when: There is a pyproject.toml or uv.lock

Key commands:

uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Sync the environment and update the lockfile if needed
uv sync --locked          # Require an up-to-date lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version
Tools

Use uv run for tools declared in the project, such as uv run pytest or
uv run ruff check .. This uses the project's locked tool versions and makes
its dependencies available to the command. Use uvx for standalone tools that
can run in an isolated environment.

Key commands:

uvx <tool> <args>            # Run a tool in an isolated environment
uvx <tool>@<version> <args>  # Run a specific version of a tool

Important:

  • uvx runs tools from PyPI by package name. This can be unsafe - only run

well-known tools.

  • Only use uv tool install only when specifically requested by the user.
Type checking

Use uv check to type check a uv project with ty. It syncs the project
environment and uses the version of ty in uv.lock when ty is a project
dependency or a member of the dev dependency group. Otherwise, uv selects a
compatible version of ty.

For a PEP 723 script, use uv check --script script.py to check it with its
inline dependencies.

Pip interface

Use when: Legacy workflows with requirements.txt or manual environment
management, no uv.lock present.

Key commands:

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt

Important:

  • Don't use the pip interface unless clearly needed.
  • Don't introduce new requirements.txt files.
  • Prefer uv init for new projects.
Migrating from other tools
pyenv → uv python
pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default
pipx → uvx
pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list
pip and pip-tools → uv pip
pip install package      → uv pip install package
pip install -r req.txt   → uv pip install -r req.txt
pip freeze               → uv pip freeze
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv
Common patterns
Don't use pip in uv projects
# Bad
pip install requests

# Good
uv add requests
Don't run python directly
# Bad
python script.py

# Good
uv run script.py
# Bad
python -c "..."

# Good
uv run python -c "..."
# Bad
python3.12 -c "..."

# Good
uv run --python 3.12 python -c "..."

Use uvx python@3.12 when you explicitly want a standalone interpreter.

Don't manually manage environments in uv projects
# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>
Documentation

For detailed information, read the official documentation:

  • https://docs.astral.sh/uv/llms.txt

The documentation links to specific pages for each of these workflows.

Install

Related Skills

See all uv alternatives

Ten SKILL.md modules that give coding agents real ROS engineering judgement — ROS 1 and ROS 2, design patterns, perception, testing, Docker, bringup and robot security.

New

The skill for Vercel Labs' agent-browser, a fast Rust CLI that lets coding agents open sites, fill forms, click, screenshot and scrape through Chrome DevTools Protocol, using accessibility-tree snapshots with stable element refs.

New

Vercel's skill for discovering agent skills: when you ask how to do something, the agent searches the open skills ecosystem with the Skills CLI, vets results by installs, source and stars, and offers the install command.

Browse all skills →