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

1. ✅ Verify Python 3.10+
2. ✅ Install UV (required package manager)
3. ✅ Setup virtual environment with UV
4. ✅ Install dependencies
5. ✅ Setup Ruff (linting + formatting)
6. ✅ Setup MyPy (type checking)
7. ✅ Setup pytest (testing)
8. ✅ Setup pre-commit hooks
9. ✅ Verify imports and dependencies
10. ✅ Run quality checks
11. ✅ Run tests
12. ✅ 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

1. Always use UV - Never use pip directly
2. Use pyproject.toml - Modern Python standard
3. Use Ruff - Replaces flake8, black, isort (faster)
4. Lock dependencies - Use uv lock or uv pip compile
5. Pin Python version - Use uv python pin
6. Enable mypy strict mode - Catch type errors early
7. Use pre-commit hooks - Automate checks
8. 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