UV - Python Package and Project Manager

Overview

This skill provides workflows for working with uv, an extremely fast Python package and project manager. It focuses on project initialization with smart source directory setup and dependency management.

CRITICAL - Always Use UV

ALWAYS use uv for any Python operations in Python projects:

• Running Python scripts: uv run python script.py (NOT python script.py)
• Running commands: uv run <command> (NOT direct execution)
• Installing packages: uv add <package> or uv pip install <package> (NOT pip install)
• Creating virtual environments: uv venv (NOT python -m venv)

Never use pip, python, or virtualenv directly in uv-managed projects.

When to Use This Skill

Use this skill when the user wants to:

• Create a new Python project or application
• Initialize a Python project structure
• Add dependencies to a Python project
• Set up a Python project with proper package structure

Project Initialization

To initialize a new Python application project:

1. Run uv init to create the project structure
2. Read the generated pyproject.toml to extract the project name
3. Check if a directory matching the project name exists in the current directory
4. If a matching directory exists:
   • CRITICAL: Create __init__.py inside that directory (NOT in the current directory)
   • Update pyproject.toml to add the directory as a source package to make it installable
5. Provide clear feedback about what was created and configured

Example Workflow

When a user says "Create a new Python project called myapp":

# Initialize the project
uv init

# Read pyproject.toml to get the project name
# Extract the name field (e.g., "myapp")

# Check if directory exists
ls myapp/

# If myapp/ directory exists:
# 1. Create __init__.py IN THE myapp/ DIRECTORY
echo "" > myapp/__init__.py

# 2. Update pyproject.toml to make the directory installable
# Add or update the [tool.uv] or [project] section to include:
# packages = [{include = "myapp"}]

Important Notes:

• The __init__.py file must be created in the project-named directory, NOT in the current working directory
• Only perform the source directory setup if a matching directory already exists
• The pyproject.toml modification makes the package installable with uv pip install -e .

Dependency Management

To add dependencies to a project:

Use uv add <package> directly:

# Add a single package
uv add numpy

# Add multiple packages
uv add requests pandas matplotlib

# Add development dependencies
uv add --dev pytest black mypy

The uv add command automatically:

• Adds the package to pyproject.toml
• Updates uv.lock
• Installs the package in the virtual environment

Resources

For additional uv commands and usage patterns, see references/uv_commands.md.