AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

modern-python

Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--modern-python at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/uv-commands.md

uv Command Reference

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

Key principle: Always use uv run to execute commands. Never manually activate virtual environments.

Installation

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# pipx
pipx install uv

Project Commands

Initialize Projects

| Command | Description | |---------|-------------| | uv init | Create new project (application) | | uv init --package | Create distributable package with src/ layout | | uv init --lib | Create library package | | uv init --script file.py | Create script with PEP 723 metadata |

Dependency Management

| Command | Description | |---------|-------------| | uv add <pkg> | Add dependency to project | | uv add <pkg> --group dev | Add to dependency group | | uv add <pkg> --optional feature | Add to optional dependency | | uv remove <pkg> | Remove dependency | | uv lock | Update lock file without installing |

Environment Management

uv manages virtual environments automatically. Do not manually create or activate venvs.

| Command | Description | |---------|-------------| | uv sync | Install dependencies (creates venv if needed) | | uv sync --all-groups | Install all dependency groups | | uv sync --group dev | Install specific group | | uv sync --frozen | Install from lock file exactly |

Running Code

| Command | Description | |---------|-------------| | uv run <cmd> | Run command in project venv | | uv run python script.py | Run Python script | | uv run pytest | Run pytest | | uv run --with pkg cmd | Run with temporary dependency |

Building & Publishing

| Command | Description | |---------|-------------| | uv build | Build wheel and sdist | | uv build --wheel | Build wheel only | | uv build --sdist | Build sdist only | | uv publish | Publish to PyPI | | uv publish --token $TOKEN | Publish with API token |

Tool Commands

Run Python tools without installing globally:

# Run any tool
uv tool run ruff check .
uvx ruff check .  # shorthand

# Install tool globally
uv tool install ruff

# List installed tools
uv tool list

# Upgrade tool
uv tool upgrade ruff

Python Version Management

# Install Python version
uv python install 3.12

# List available versions
uv python list

# Pin project to Python version
uv python pin 3.12

# Use specific version
uv run --python 3.11 pytest

Script Commands (PEP 723)

# Create script with inline metadata
uv init --script myscript.py

# Add dependency to script
uv add --script myscript.py requests

# Run script (auto-installs deps)
uv run myscript.py

Common Workflows

New Application Project

uv init myapp
cd myapp
uv add fastapi uvicorn
uv add --group dev ruff pytest
uv sync --all-groups
uv run uvicorn myapp:app

New Library Package

uv init --package mylib
cd mylib
uv add --group dev ruff pytest pytest-cov
uv add --group docs sphinx
uv sync --all-groups
uv run pytest
uv build

Add Tool to Existing Project

cd existing-project
uv add --group dev ruff
uv run ruff check .

One-off Script Execution

# Run script with dependencies (no project needed)
uv run --with requests --with rich script.py

# Or use PEP 723 inline metadata
uv run script_with_metadata.py

Environment Variables

| Variable | Description | |----------|-------------| | UV_CACHE_DIR | Cache directory location | | UV_NO_CACHE | Disable caching | | UV_PYTHON | Default Python version | | UV_PROJECT | Project directory path | | UV_PROJECT_ENVIRONMENT | Custom venv directory (e.g., .venv-dev) | | UV_SYSTEM_PYTHON | Use system Python |

Container/Host Development

When developing on a host machine while also running in containers, you can use separate venvs to avoid rebuilding on each context switch:

# On host machine (add to shell profile or .envrc)
export UV_PROJECT_ENVIRONMENT=.venv-dev

# Now host uses .venv-dev, containers use default .venv
uv sync  # creates .venv-dev on host

Add both to .gitignore:

.venv/
.venv-dev/

This avoids rebuilding the venv when switching between host and container (different OS, Python versions, or native dependencies).

Performance Tips

  • uv caches aggressively; first install may be slower
  • Use uv sync --frozen in CI for reproducible builds
  • Use uv cache clean if cache grows too large