astral-sh/agent-plugins

uv

Guide for using uv, the Python package and project manager.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/astral-sh/agent-plugins --skill uv

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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:

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

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

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

bash
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

bash
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

bash
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

bash
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

bash
# Bad
pip install requests

# Good
uv add requests

Don't run python directly

bash
# Bad
python script.py

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

# Good
uv run python -c "..."
bash
# 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

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