Environment Setup Checklist

Python 3.14, uv, editor, and tooling setup - get from clone to green tests in minutes on macOS or Linux.

How to Use This Checklist

• Complete in order on a fresh machine or new repo clone.
• Check each box before moving to app-specific steps.
• If a step fails, stop and fix - do not skip lockfile or venv steps.
• Paste exact versions from pyproject.toml when reporting setup issues.

Core Runtime

1. Install uv 0.6+: curl -LsSf https://astral.sh/uv/install.sh | sh or package manager per org policy.
2. Install Python 3.14: uv python install 3.14 if not system-wide.
3. Clone repository: SSH key configured; git clone git@github.com:acme/service.git.
4. Enter project: cd service - confirm pyproject.toml and uv.lock present.
5. Sync dependencies: uv sync --all-extras (or --extra dev per README).

Quality Tools

6. Run linter: uv run ruff check . - zero errors on clean main.
7. Run formatter check: uv run ruff format --check . or format once.
8. Run tests: uv run pytest -q - full suite or README subset for first pass.
9. Typecheck (if configured): uv run mypy src/ or uv run pyright.
10. Install pre-commit: uv run pre-commit install then pre-commit run --all-files.

Application Config

11. Copy env template: cp .env.example .env - fill local values from 1Password/vault doc.
12. Never commit .env: Confirm listed in .gitignore.
13. Database (if needed): Docker compose docker compose up -d db or documented local Postgres.
14. Migrations: uv run alembic upgrade head or Django migrate per project.
15. Start dev server: uv run uvicorn app.main:app --reload - curl /health.

Editor & Git

16. Editor Python interpreter: Point to .venv/bin/python created by uv.
17. Ruff extension: Format on save aligned with pyproject.toml line length.
18. Git identity: user.name and user.email set (Git Configuration).
19. GitHub CLI (optional): gh auth login for PR workflow.
20. Shell PATH: ~/.local/bin for pipx tools (httpie, copier).

Verification Gate

21. Repeat CI locally: Same commands as .github/workflows/pr.yml (ruff, pytest, mypy).
22. Smoke HTTP: curl -sf http://localhost:8000/health returns 200.
23. Import sanity: uv run python -c "import app" no ImportError.
24. Document blockers: Open issue or Slack thread with exact error output if any step fails.
25. Sign off with buddy: Screenshot or paste terminal summary in onboarding ticket.

FAQs

Related

• uv - The Fast Toolchain - uv depth
• Onboarding Devs Checklist - full ramp
• Python-in-the-Shell - shell usage
• Managing Python Versions - version policy

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.