Python Development Setup Skill

Purpose

Quickly set up and verify a Python development environment using UV for fast, reliable dependency management.

CRITICAL: Always Use UV

NEVER use pip directly. ALWAYS use UV for Python dependency management.

UV is 10-100x faster than pip and provides:

Deterministic dependency resolution
Lockfile support
Virtual environment management
Drop-in pip replacement

Workflow

Quick Setup Checklist

✅ Verify Python 3.10+
✅ Install UV (required package manager)
✅ Setup virtual environment with UV
✅ Install dependencies
✅ Setup Ruff (linting + formatting)
✅ Setup MyPy (type checking)
✅ Setup pytest (testing)
✅ Setup pre-commit hooks
✅ Verify imports and dependencies
✅ Run quality checks
✅ Run tests
✅ Verify environment reproducibility

For detailed step-by-step instructions with UV commands and troubleshooting, see references/DETAILED-WORKFLOW.md.

Troubleshooting

Issue: "uv: command not found"

Solution: UV not installed

curl -LsSf https://astral.sh/uv/install.sh | sh
# Then restart shell or source profile

Issue: "No Python found"

Solution: Install Python with UV

uv python install 3.12

Issue: "Resolution failed"

Solution: Dependency conflict

# Show what's conflicting
uv pip install --dry-run -r requirements.txt

# Try with looser constraints
uv pip install --resolution=lowest .

Issue: "ModuleNotFoundError: No module named 'X'"

Solution: Dependency not installed

uv pip install -e ".[dev]"
# or
uv pip install <module-name>

Best Practices

Always use UV - Never use pip directly
Use pyproject.toml - Modern Python standard
Use Ruff - Replaces flake8, black, isort (faster)
Lock dependencies - Use uv lock or uv pip compile
Pin Python version - Use uv python pin
Enable mypy strict mode - Catch type errors early
Use pre-commit hooks - Automate checks
Target 90%+ coverage - Comprehensive testing

Migration from pip

If you have an existing project using pip:

# Create new venv with UV
rm -rf venv .venv
uv venv

# Activate
source .venv/bin/activate

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

# Generate lock file
uv pip compile requirements.txt -o requirements.lock

Integration with Other Skills

This skill may be invoked by:

quality-check - When checking Python code quality
run-tests - When running Python tests

setup-python

Safety Notice

Copy this and send it to your AI assistant to learn