Uvicorn

Warnings

• breaking UvicornWorker moved to separate uvicorn-worker package. uvicorn.workers.UvicornWorker import path no longer works in current versions. LLM-generated Gunicorn configs still use the old path.
  Fix: pip install uvicorn-worker, then use: gunicorn app:app -k uvicorn_worker.UvicornWorker
• breaking Python 3.8 and 3.9 support dropped. uvicorn>=0.32.0 requires Python >=3.10.
  Fix: Pin uvicorn<0.32.0 for Python 3.8/3.9, or upgrade Python.
• breaking config.setup_event_loop() removed in 0.36.0 as an undocumented internal. Broke downstream packages (including uvicorn-worker<0.4.0) that called it directly.
  Fix: Upgrade uvicorn-worker to >=0.4.0 if using Gunicorn. Do not call config.setup_event_loop() directly.
• breaking bare pip install uvicorn has no uvloop, httptools, or watchfiles. --reload requires watchfiles; without it the flag is silently ignored on some versions.
  Fix: Use pip install 'uvicorn[standard]' for development. For production containers, install uvicorn[standard] or add uvloop and httptools explicitly for performance.
• gotcha --workers and --reload are mutually exclusive. Using both raises an error.
  Fix: Use --reload only in development (single process). Use --workers only in production.
• gotcha When passing workers>1 to uvicorn.run(), the app argument must be an import string like 'main:app', not an app instance. Passing an instance raises: ValueError: You must pass the application as an import string.
  Fix: uvicorn.run('main:app', workers=4) — always use import string with multiple workers.
• gotcha uvloop is not available on Windows. uvicorn[standard] will skip uvloop on Windows silently and fall back to the default asyncio event loop. Performance characteristics differ from Linux.
  Fix: Expected behavior on Windows. No fix needed, but be aware of performance differences between dev (Windows) and prod (Linux).

Install

• pip install uvicorn Minimal (pure Python, no uvloop/httptools)
• pip install "uvicorn[standard]" Recommended (includes uvloop, httptools, watchfiles, websockets)
• pip install uvicorn-worker Gunicorn worker class (separate package since 0.21)

Imports

• UvicornWorker

  from uvicorn_worker import UvicornWorker  # separate package
  # gunicorn app:app -w 4 -k uvicorn_worker.UvicornWorker

  UvicornWorker was moved to the uvicorn-worker package (pip install uvicorn-worker). uvicorn.workers still exists in some versions but is deprecated and will raise ImportError.
• uvicorn.run

  uvicorn.run('main:app', host='0.0.0.0', port=8000, workers=4)

  When using workers>1, the app argument must be an import string ('module:attr'), not an app instance. Passing an app instance with workers raises a ValueError.

Quickstart

Common invocation patterns. Import string required for --workers and Gunicorn.

# Development
uvicorn main:app --reload

# Production (single process)
uvicorn main:app --host 0.0.0.0 --port 8000

# Production (multiple workers — import string required)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# Programmatic
import uvicorn

if __name__ == '__main__':
    uvicorn.run('main:app', host='0.0.0.0', port=8000, reload=True)

# Gunicorn + UvicornWorker (install uvicorn-worker separately)
# gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker