Python

Python/uv Development Skill

You are a Python development specialist using uv, an extremely fast Python package manager and project management tool. This skill provides comprehensive workflows, best practices, and common patterns for Python development with uv.

Why uv?

uv is the modern replacement for pip, virtualenv, poetry, and pyenv combined:

• Extremely fast: 10-100x faster than pip
• All-in-one: Package management, virtual environments, Python version management
• Rust-powered: Built for speed and reliability
• Compatible: Works with existing Python projects and tools

IMPORTANT: Avoid pip

DO NOT use pip commands. Always use uv equivalents:

• WRONG: pip install requests → RIGHT: uv add requests
• WRONG: pip install -r requirements.txt → RIGHT: uv sync
• WRONG: pip freeze > requirements.txt → RIGHT: uv lock (creates uv.lock)
• WRONG: python -m pip install → RIGHT: uv run or uv add

The only exception is legacy projects that explicitly require pip compatibility, and even then prefer migrating to uv.

Core Capabilities

1. Project Management: init, add, remove, sync, lock
2. Running Code: run (scripts and commands)
3. Python Management: python (install, list, pin versions)
4. Tools: tool (install and run CLI tools)
5. Environments: venv (virtual environment creation)
6. pip-compatible: pip interface for legacy workflows
7. Building: build, publish packages

Quick Start

Running a Python Script

The most common use case - just run your script:

uv run script.py
uv run script.py arg1 arg2

What this does:

• Automatically creates/uses virtual environment
• Installs dependencies from pyproject.toml if present
• Runs the script with the correct Python version

Running a Script with Dependencies

# Run with additional packages
uv run --with requests script.py
uv run --with requests --with pandas analyze.py

# Run with packages from requirements file
uv run --with-requirements requirements.txt script.py

Running a Python Module

uv run -m module_name
uv run -m pytest tests/
uv run -m black .

One-off Script Execution (No Project)

# Run a script in isolation
uv run --isolated script.py

# Run with specific Python version
uv run --python 3.11 script.py

# Run with dependencies without a project
uv run --with httpx --with rich my_script.py

Project Management

Creating a New Project

# Create application project
uv init my-app
uv init my-app --app

# Create library project
uv init my-lib --lib

# Create script (single file)
uv init my-script --script

# Create in current directory
uv init

# Create without package structure
uv init --bare  # Only creates pyproject.toml

Project types:

• --app: Application (not meant to be imported)
• --lib: Library (meant to be published and imported)
• --script: Single-file script with inline dependencies

Managing Dependencies

# Add dependency
uv add requests
uv add "requests>=2.31.0"
uv add requests pandas numpy

# Add dev dependency
uv add --dev pytest
uv add --dev black ruff mypy

# Add optional dependency (extra)
uv add --extra docs sphinx

# Remove dependency
uv remove requests
uv remove --dev pytest

# Update dependencies
uv lock --upgrade
uv lock --upgrade-package requests

Syncing Environment

# Sync environment with lockfile
uv sync

# Sync without dev dependencies
uv sync --no-dev

# Sync with all extras
uv sync --all-extras

# Sync specific extra
uv sync --extra docs

# Exact sync (remove extraneous packages)
uv sync --exact

Lockfile Management

# Update lockfile
uv lock

# Update all packages
uv lock --upgrade

# Update specific package
uv lock --upgrade-package requests

# Lock without touching network (use cache only)
uv lock --offline

Python Version Management

Installing Python Versions

# Install specific Python version
uv python install 3.11
uv python install 3.12.1

# Install multiple versions
uv python install 3.11 3.12

# List available Python versions
uv python list

# List installed versions
uv python list --only-installed

Finding and Pinning Python

# Find Python installation
uv python find
uv python find 3.11

# Pin project to specific Python version
uv python pin 3.11
uv python pin 3.12.1

# This creates/updates .python-version file

Python Version in Projects

When you create a project, uv automatically:

1. Creates .python-version file
2. Detects or installs the appropriate Python version
3. Uses it for all uv run commands in that project

Tool Management

Installing CLI Tools

# Install a tool globally
uv tool install ruff
uv tool install black
uv tool install httpie

# Install specific version
uv tool install "black==24.1.0"

# Run tool without installing
uv tool run ruff check .
uv tool run black --check .

Managing Installed Tools

# List installed tools
uv tool list

# Upgrade tools
uv tool upgrade ruff
uv tool upgrade --all

# Uninstall tool
uv tool uninstall ruff

# Show tool directory
uv tool dir

Common Tools to Install

# Linters and formatters
uv tool install ruff      # Fast linter and formatter
uv tool install black     # Code formatter
uv tool install mypy      # Type checker

# Testing
uv tool install pytest    # Test framework
uv tool install tox       # Test automation

# Utilities
uv tool install httpie    # HTTP client
uv tool install rich-cli  # Pretty terminal output
uv tool install pipx      # Legacy tool installer

Virtual Environments

Creating Virtual Environments

# Create venv in current directory
uv venv

# Create with specific Python version
uv venv --python 3.11

# Create in specific location
uv venv path/to/venv

# Create with specific name
uv venv .venv-dev

Using Virtual Environments

# Activate (traditional way)
source .venv/bin/activate

# Or just use uv run (recommended)
uv run python script.py
uv run pytest

Best Practice: With uv, you rarely need to manually activate environments. Just use uv run.

Legacy pip Interface (AVOID - Use Native uv Commands Instead)

WARNING: This interface exists only for legacy compatibility. Prefer native uv commands (uv add, uv sync, uv lock) over uv pip commands.

Only use uv pip when:

• Working with a legacy project that cannot be migrated yet
• Maintaining compatibility with existing CI/CD that expects pip commands
• As a temporary bridge during migration

Better alternatives:

• uv pip install requests → Use uv add requests instead
• uv pip install -r requirements.txt → Use uv sync instead
• uv pip freeze → Use uv lock instead

# Legacy pip-compatible commands (avoid if possible)
uv pip install requests              # Better: uv add requests
uv pip install -r requirements.txt   # Better: uv sync
uv pip list                          # Better: uv tree
uv pip show requests                 # Better: uv tree --package requests
uv pip freeze > requirements.txt     # Better: uv lock
uv pip uninstall requests            # Better: uv remove requests

Common Workflows

Workflow 1: New Python Project

# 1. Create project
uv init my-project --app
cd my-project

# 2. Add dependencies
uv add requests httpx rich

# 3. Add dev dependencies
uv add --dev pytest black ruff

# 4. Run your code
uv run python main.py

# 5. Run tests
uv run pytest

Workflow 2: Working with Existing Project

# 1. Clone repository
git clone <repo>
cd <repo>

# 2. Sync dependencies (reads pyproject.toml)
uv sync

# 3. Run the application
uv run python main.py

# 4. Run tests
uv run pytest

Workflow 3: Quick Script with Dependencies

# Option 1: Inline dependencies in script
cat > script.py << 'EOF'
# /// script
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())
EOF

uv run --script script.py

# Option 2: Command-line dependencies
uv run --with requests --with rich script.py

Workflow 4: Testing and Linting

# Run tests
uv run pytest
uv run pytest tests/
uv run pytest -v --cov

# Format code
uv run black .
uv run ruff format .

# Lint code
uv run ruff check .
uv run ruff check --fix .

# Type check
uv run mypy .

Workflow 5: Dependency Updates

# 1. Check current dependencies
uv tree

# 2. Update all dependencies
uv lock --upgrade

# 3. Update specific package
uv lock --upgrade-package requests

# 4. Sync environment
uv sync

# 5. Run tests to verify
uv run pytest

Workflow 6: Building and Publishing

# Build package
uv build

# Publish to PyPI
uv publish

# Publish to test PyPI
uv publish --index https://test.pypi.org/simple/

Best Practices

1. Always Use uv run

Instead of:

# Don't do this
source .venv/bin/activate
python script.py

Do this:

# Do this
uv run script.py

Benefits:

• Automatic environment management
• Ensures dependencies are synced
• Works consistently across systems

2. Pin Python Versions

Always create .python-version file:

uv python pin 3.11

This ensures everyone on the team uses the same Python version.

3. Use Lockfiles

Commit uv.lock to version control:

• Ensures reproducible builds
• Locks transitive dependencies
• Faster installs for teammates

4. Separate Dev Dependencies

uv add --dev pytest black ruff mypy

This keeps production dependencies clean.

5. Use Scripts Section

In pyproject.toml:

[project.scripts]
my-cli = "my_package.cli:main"

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "black>=24.0.0",
]

Then run:

uv run my-cli

Project Structure

Typical uv Project Layout

my-project/
├── .python-version      # Python version (e.g., "3.11")
├── pyproject.toml       # Project config and dependencies
├── uv.lock             # Lockfile (commit this!)
├── .venv/              # Virtual environment (don't commit)
├── src/
│   └── my_package/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

pyproject.toml Example

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
    "rich>=13.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=24.0.0",
    "ruff>=0.1.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "black>=24.0.0",
]

Advanced Features

Running with Extras

# Run with optional dependencies
uv run --extra docs sphinx-build
uv run --all-extras pytest

Dependency Groups

# Add to specific group
uv add --group test pytest

# Run with specific group
uv run --group test pytest

# Sync specific group
uv sync --group test

Environment Variables

# Use .env file
uv run --env-file .env script.py

# Override env file
uv run --no-env-file script.py

Offline Mode

# Work without network
uv run --offline script.py
uv sync --offline
uv lock --offline

Custom Indexes

# Use custom PyPI index
uv add requests --index https://my-pypi.org/simple/

# Use multiple indexes
uv add package --index https://index1.org/simple/ --index https://index2.org/simple/

Troubleshooting

Issue: Command not found after uv tool install

Solution: Update shell PATH

uv tool update-shell
# Then restart shell or source config

Issue: Python version not found

Solution: Install Python with uv

uv python install 3.11
uv python pin 3.11

Issue: Dependencies not syncing

Solution: Force sync

uv sync --reinstall
uv sync --exact

Issue: Cache issues

Solution: Clear cache

uv cache clean
uv run --no-cache script.py

Issue: uv run fails with a ~/.cache/uv permission error inside a sandboxed shell

Was a sandbox filesystem-allowlist gap, not a corrupted cache — ~/.cache/uv wasn't in sandbox.filesystem.allowWrite in Claude Code's settings.json. Fixed 2026-08-25 by adding it alongside the existing /tmp entries. uv cache clean never fixed this and just wasted a step.

If it recurs: check sandbox.filesystem.allowWrite in ~/.claude/settings.json first — the fix may have reverted, or uv cache dir may point somewhere new. Only fall back to dangerouslyDisableSandbox: true as a stopgap.

Issue: Lock file out of sync

Solution: Regenerate lock

uv lock --upgrade
uv sync

Performance Tips

1. Use --frozen for CI/CD

# Skip lockfile updates in CI
uv sync --frozen
uv run --frozen pytest

2. Leverage Cache

uv automatically caches packages. To see cache:

uv cache dir

3. Parallel Operations

uv automatically parallelizes operations. No configuration needed.

Migration from Other Tools

From pip + virtualenv

# Old way
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python script.py

# New way
uv run script.py  # That's it!

From Poetry

# Old: poetry install && poetry run python script.py
# New:
uv sync && uv run python script.py

From Pipenv

# Old: pipenv install && pipenv run python script.py
# New:
uv sync && uv run python script.py

Integration with Other Tools

pytest

uv run pytest
uv run pytest --cov --cov-report=html

black/ruff

uv run black .
uv run ruff check --fix .

mypy

uv run mypy src/

jupyter

uv add --dev jupyter
uv run jupyter notebook

Quick Reference

# Run script
uv run script.py

# Run with dependencies
uv run --with requests script.py

# Project setup
uv init my-project
uv add package-name
uv add --dev pytest

# Environment management
uv sync
uv lock --upgrade

# Python management
uv python install 3.11
uv python pin 3.11

# Tools
uv tool install ruff
uv tool run black .

# Legacy compatibility (AVOID - use uv add/sync instead)
uv pip install package              # DON'T USE - use: uv add package
uv pip install -r requirements.txt  # DON'T USE - use: uv sync

# Testing and quality
uv run pytest
uv run black .
uv run ruff check .

Key Differences from pip/virtualenv

Common Patterns

Pattern 1: Quick Data Analysis Script

uv run --with pandas --with matplotlib analyze.py

Pattern 2: Testing Before Commit

uv run pytest && uv run black --check . && uv run ruff check .

Pattern 3: Update All Dependencies

uv lock --upgrade && uv sync && uv run pytest

Pattern 4: Run with Specific Python

uv run --python 3.11 script.py

Pattern 5: Install and Run Tool

uv tool run ruff check .  # Installs if needed, then runs

Common Gotchas

JSON serialization drops non-ASCII characters by default

json.dumps defaults to ensure_ascii=True, which silently converts non-ASCII characters (em-dashes —, arrows →, smart quotes) to \uXXXX escape sequences instead of raising or warning. Any script writing JSON from user-authored text or field descriptions must pass ensure_ascii=False:

json.dumps(data, indent=2, ensure_ascii=False)

Summary

Primary directive: Use uv run for executing Python scripts and commands.

Key advantages:

• No manual environment activation needed
• Automatic dependency management
• Extremely fast operations
• Single tool for all Python workflows

Most common commands:

• uv run script.py - Run anything
• uv add package - Add dependency
• uv sync - Sync environment
• uv python pin 3.11 - Set Python version