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

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

Quality Tools

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

Application Config

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

Editor & Git

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

Verification Gate

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

FAQs

uv sync fails on Apple Silicon?

Check wheels for native deps (torch, etc.) - use documented extras or CPU-only index.

Wrong Python version picked?

uv python pin 3.14 in project or .python-version file per README.

poetry.lock in old branch?

Follow README migration note - may need rebase onto uv migration commit first.

Windows developers?

WSL2 Ubuntu recommended; same checklist inside WSL.

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+.

Core Runtime

Install uv 0.6+: curl -LsSf https://astral.sh/uv/install.sh | sh or package manager per org policy.

Install Python 3.14: uv python install 3.14 if not system-wide.

Clone repository: SSH key configured; git clone git@github.com:acme/service.git.

Enter project: cd service - confirm pyproject.toml and uv.lock present.

Sync dependencies: uv sync --all-extras (or --extra dev per README).

Quality Tools

Run linter: uv run ruff check . - zero errors on clean main.

Run formatter check: uv run ruff format --check . or format once.

Run tests: uv run pytest -q - full suite or README subset for first pass.

Typecheck (if configured): uv run mypy src/ or uv run pyright.

Install pre-commit: uv run pre-commit install then pre-commit run --all-files.

Application Config

Copy env template: cp .env.example .env - fill local values from 1Password/vault doc.

Never commit .env: Confirm listed in .gitignore.

Database (if needed): Docker compose docker compose up -d db or documented local Postgres.

Migrations: uv run alembic upgrade head or Django migrate per project.

Start dev server: uv run uvicorn app.main:app --reload - curl /health.

Editor & Git

Editor Python interpreter: Point to .venv/bin/python created by uv.

Ruff extension: Format on save aligned with pyproject.toml line length.

Git identity: user.name and user.email set (Git Configuration).

GitHub CLI (optional): gh auth login for PR workflow.

Shell PATH: ~/.local/bin for pipx tools (httpie, copier).

Verification Gate

Repeat CI locally: Same commands as .github/workflows/pr.yml (ruff, pytest, mypy).

Smoke HTTP: curl -sf http://localhost:8000/health returns 200.

Import sanity: uv run python -c "import app" no ImportError.

Document blockers: Open issue or Slack thread with exact error output if any step fails.

Sign off with buddy: Screenshot or paste terminal summary in onboarding ticket.

FAQs

uv sync fails on Apple Silicon?

Check wheels for native deps (torch, etc.) - use documented extras or CPU-only index.

Wrong Python version picked?

uv python pin 3.14 in project or .python-version file per README.

poetry.lock in old branch?

Follow README migration note - may need rebase onto uv migration commit first.

Windows developers?

WSL2 Ubuntu recommended; same checklist inside WSL.

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+.

Environment Setup Checklist

Search Documentation

Environment Setup Checklist