---
description: UV package manager usage patterns for Python dependency management for Trax project
alwaysApply: false
---
# UV Package Manager Rule

## Core Principles
- **UV First**: Use UV for all Python package management
- **Directory Awareness**: Run commands from the correct directory
- **Environment Activation**: Ensure virtual environment is active
- **Dependency Management**: Use pyproject.toml for dependencies

## Implementation Patterns

### Package Installation
```bash
# ✅ DO: Use UV for package installation
# Install dependencies
uv pip install -e ".[dev]"

# Install a specific package
uv pip install package-name

# Install a development dependency
uv pip install package-name --dev
```

### Running Python Commands
```bash
# ✅ DO: Use UV run for Python commands
# Run a Python script
uv run python src/main.py

# Run a test suite
uv run pytest

# Run a formatter
uv run black src/ tests/
```

### Dependency Management
```bash
# ✅ DO: Update requirements.txt with UV
# Compile dependencies from pyproject.toml
uv pip compile pyproject.toml -o requirements.txt
```

### Anti-Patterns
```bash
# ❌ DON'T: Use pip directly
pip install package-name  # Wrong! Use uv pip instead

# ❌ DON'T: Run Python commands directly
python src/main.py  # Wrong! Use uv run python instead

# ❌ DON'T: Run tools directly
pytest  # Wrong! Use uv run pytest instead
```

Before running any Python command or tool, ensure you are in the correct directory and that your virtual environment is activated. Always use `uv pip` for package management and `uv run` for executing Python commands and tools.