uv

Original source / Raw SKILL.md

---
name: uv
description: This skill should be used when creating new Python projects or managing Python dependencies. IMPORTANT - uv must ALWAYS be used for any Python-related commands in Python projects (running scripts, installing packages, creating virtual environments, etc.). Never use pip, python directly, or other package managers - always use uv commands (uv run, uv add, uv pip, etc.).
---

# 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":

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

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


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/uv_commands.md

```markdown
# UV Command Reference

This document provides a quick reference for common uv commands and usage patterns.

## Project Management

### Initialize a New Project

```bash
# Create a new application project
uv init

# Create a new project with a specific name
uv init my-project

# Create a new library project
uv init --lib
```

### Project Structure

After `uv init`, the typical structure includes:

```
my-project/
├── pyproject.toml    # Project metadata and dependencies
├── README.md         # Project documentation
├── .python-version   # Python version specification
└── hello.py          # Example entry point (for applications)
```

## Dependency Management

### Adding Dependencies

```bash
# Add a runtime dependency
uv add requests

# Add multiple dependencies
uv add numpy pandas matplotlib

# Add a development dependency
uv add --dev pytest

# Add with version constraints
uv add "django>=4.0,<5.0"

# Add from a specific index
uv add --index-url https://pypi.org/simple requests
```

### Removing Dependencies

```bash
# Remove a dependency
uv remove requests

# Remove multiple dependencies
uv remove numpy pandas
```

### Updating Dependencies

```bash
# Update all dependencies
uv lock --upgrade

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

# Sync the environment with the lock file
uv sync
```

## Virtual Environment Management

```bash
# Create a virtual environment
uv venv

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

# Activate the virtual environment (Unix/Mac)
source .venv/bin/activate

# Activate the virtual environment (Windows)
.venv\Scripts\activate
```

## Running Commands

```bash
# Run a Python script
uv run python script.py

# Run a command in the project environment
uv run pytest

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

## Package Installation

```bash
# Install the current project in editable mode
uv pip install -e .

# Install from requirements.txt
uv pip install -r requirements.txt

# Install a specific package
uv pip install numpy
```

## Python Version Management

```bash
# Install a specific Python version
uv python install 3.11

# List available Python versions
uv python list

# Set the Python version for a project
uv python pin 3.11
```

## pyproject.toml Structure

### Basic Configuration

```toml
[project]
name = "my-project"
version = "0.1.0"
description = "A sample project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.31.0",
    "numpy>=1.24.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]

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

### Making a Directory Installable

To make a source directory installable as a package:

```toml
[tool.hatch.build.targets.wheel]
packages = ["myapp"]
```

Or using setuptools:

```toml
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["."]
include = ["myapp*"]
```

## Common Workflows

### Starting a New Project

```bash
# Create and initialize
uv init my-project
cd my-project

# Add dependencies
uv add requests pandas

# Create virtual environment and install
uv venv
uv pip install -e .
```

### Converting from requirements.txt

```bash
# Initialize uv project
uv init

# Import dependencies from requirements.txt
uv add $(cat requirements.txt | grep -v "^#" | grep -v "^$" | tr '\n' ' ')

# Or install directly
uv pip install -r requirements.txt
```

### Development Workflow

```bash
# Add dev dependencies
uv add --dev pytest black mypy ruff

# Run tests
uv run pytest

# Format code
uv run black .

# Type check
uv run mypy .

# Lint
uv run ruff check .
```

## Performance Notes

- uv is written in Rust and is significantly faster than pip
- Lock files are resolved in parallel for maximum speed
- Virtual environment creation is nearly instantaneous
- Package installation is optimized with caching

## Additional Resources

- Official documentation: https://docs.astral.sh/uv/
- GitHub repository: https://github.com/astral-sh/uv

```