fastapi-local-dev skill

Overview

This skill is a concise runbook for running FastAPI in local development and production. It explains recommended commands for hot-reload development with Uvicorn and for production with Gunicorn + Uvicorn workers, plus common environment considerations. The guidance focuses on predictable behavior, import paths, and avoiding common anti-patterns.

How this skill works

The runbook specifies the exact command forms to start FastAPI with Uvicorn for development (reload mode) and with Gunicorn for production (Uvicorn worker class). It highlights how import paths affect module resolution and when to force polling for filesystem watchers (useful in WSL). It also explains why reloading plus multiple workers is an anti-pattern and warns against process-level file watchers like PM2 watch for Python apps.

When to use it

• Quick local development with automatic code reloads on change
• Running a production-grade FastAPI service behind Gunicorn
• Working in WSL where file change events may be missed
• When the project requires running from the repository root to resolve imports

Best practices

• Start dev server from repo root; use python -m uvicorn or set PYTHONPATH=. to ensure imports resolve
• Use: uvicorn app.main:app --reload for development only (single-process reload)
• Use: gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w <n> --bind :8000 for production
• Do not combine --reload with multiple workers; reload is single-process and not compatible with clustering
• If running in WSL and file changes aren’t detected, set WATCHFILES_FORCE_POLLING=true to force polling

Example use cases

• Developing endpoints locally with automatic reload after code edits
• Deploying a FastAPI service to a container or VM using Gunicorn + Uvicorn workers
• Debugging import errors by running the server with python -m uvicorn to mirror module resolution
• Running CI jobs that need deterministic startup commands for integration tests

FAQ