uv-usage

name	uv-usage
description	Provides concise guidance for using uv (Python package manager), including project workflows, pip-compatible commands, Python version management, and PEP 723 inline script dependencies. Use when users mention uv, uv run, inline dependencies, PEP 723, or Python dependency/project management.

uv Usage

Quick start

Use uv as a fast, unified tool for Python projects:

1. Initialize a project: uv init
2. Add deps: uv add <package>
3. Sync env: uv sync
4. Run commands: uv run <cmd>

uv add updates uv.lock automatically; use uv lock when you need to re-lock after manual pyproject.toml edits.

Inline dependencies (PEP 723 scripts)

Use inline metadata so a script runs standalone with uv run <script-file>.

Steps

1. Add a # /// script block at the top of the file.
2. Set requires-python and dependencies.
3. Run the script with uv run <script-file>.
4. Add or remove inline deps with uv add --script and uv remove --script.

Template

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests>=2.31",
#   "rich>=13.0",
# ]
# ///

import requests
from rich import print

print(requests.get("https://api.github.com/repos/astral-sh/uv").status_code)

Commands

uv run script.py
uv add --script script.py beautifulsoup4
uv remove --script script.py rich

Pip-compatible commands

Use these for drop-in workflows or legacy projects:

uv pip install <package>
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

Python versions and environments

uv python install 3.12
uv python pin 3.12
uv venv --python 3.12
uv run --python 3.12 -- python -V

Examples

New project

uv init demo
cd demo
uv add ruff
uv run ruff check .

Standalone script with inline deps

uv run script.py

Notes

• uv offers pip-compatible commands, but behavior can differ in edge cases.
• Use uvx <tool> (alias for uv tool run) to run tools ephemerally without installing them globally.
• Prefer project workflow (uv add, uv sync) for new work, and run uv lock when re-locking after manual pyproject.toml changes.