How does Uvicorn's --reload flag work and what does it require?

The --reload flag enables automatic server restart when Python source files change. It is designed for development workflows, saving you from manually restarting the server after every code change.

# Basic auto-reload (restarts when any .py file changes)
uvicorn main:app --reload

# Watch specific directories instead of the entire working directory
uvicorn main:app --reload --reload-dir src/
uvicorn main:app --reload --reload-dir src/ --reload-dir tests/

# Include extra file patterns to watch
uvicorn main:app --reload --reload-include "*.html" --reload-include "*.css"

# Exclude patterns from watching
uvicorn main:app --reload --reload-exclude "*.log"

# IMPORTANT: --reload and --workers are mutually exclusive!
# This will raise an error:
# uvicorn main:app --reload --workers 4  ← WRONG

How it works: Uvicorn uses the watchfiles library (installed by uvicorn[standard]) to monitor the filesystem. When a watched file changes, the server process is restarted. Without watchfiles installed, --reload falls back to a slower polling method.

Key constraint: --reload and --workers are mutually exclusive. Reload mode uses a single process with a reloader wrapper - multiple workers are not compatible. For production, disable reload and use multiple workers instead.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.