{"id":200,"library":"uvicorn","title":"Uvicorn","description":"Lightning-fast ASGI server for Python. Standard server for FastAPI and Starlette. Current version is 0.42.0 (Mar 2026). Requires Python >=3.10. The Gunicorn worker class was moved to a separate package.","status":"active","version":"0.42.0","language":"python","source_language":"en","source_url":"https://uvicorn.dev/release-notes/","tags":["web","asgi","server","fastapi","starlette","async"],"install":[{"cmd":"pip install uvicorn","lang":"bash","label":"Minimal (pure Python, no uvloop/httptools)"},{"cmd":"pip install \"uvicorn[standard]\"","lang":"bash","label":"Recommended (includes uvloop, httptools, watchfiles, websockets)"},{"cmd":"pip install uvicorn-worker","lang":"bash","label":"Gunicorn worker class (separate package since 0.21)"}],"dependencies":[{"reason":"High-performance event loop. Included in uvicorn[standard]. Not available on Windows.","package":"uvloop","optional":true},{"reason":"Faster HTTP parser. Included in uvicorn[standard].","package":"httptools","optional":true},{"reason":"Required for --reload in development. Included in uvicorn[standard].","package":"watchfiles","optional":true},{"reason":"WebSocket support. Included in uvicorn[standard].","package":"websockets","optional":true},{"reason":"Provides UvicornWorker for use with Gunicorn. Moved out of uvicorn core in 0.21.","package":"uvicorn-worker","optional":true}],"imports":[{"wrong":"from uvicorn.workers import UvicornWorker","symbol":"UvicornWorker","correct":"from uvicorn.workers import UvicornWorker"}],"quickstart":{"code":"# Development\nuvicorn main:app --reload\n\n# Production (single process)\nuvicorn main:app --host 0.0.0.0 --port 8000\n\n# Production (multiple workers — import string required)\nuvicorn main:app --host 0.0.0.0 --port 8000 --workers 4\n\n# Programmatic\nimport uvicorn\n\nif __name__ == '__main__':\n    uvicorn.run('main:app', host='0.0.0.0', port=8000, reload=True)\n\n# Gunicorn + UvicornWorker (install uvicorn-worker separately)\n# gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker","lang":"bash","description":"Common invocation patterns. Import string required for --workers and Gunicorn."},"warnings":[{"fix":"pip install uvicorn-worker, then use: gunicorn app:app -k uvicorn_worker.UvicornWorker","message":"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.","severity":"breaking","affected_versions":">= 0.21.0"},{"fix":"Pin uvicorn<0.32.0 for Python 3.8/3.9, or upgrade Python.","message":"Python 3.8 and 3.9 support dropped. uvicorn>=0.32.0 requires Python >=3.10.","severity":"breaking","affected_versions":">= 0.32.0"},{"fix":"Upgrade uvicorn-worker to >=0.4.0 if using Gunicorn. Do not call config.setup_event_loop() directly.","message":"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.","severity":"breaking","affected_versions":">= 0.36.0"},{"fix":"Use pip install 'uvicorn[standard]' for development. For production containers, install uvicorn[standard] or add uvloop and httptools explicitly for performance.","message":"bare pip install uvicorn has no uvloop, httptools, or watchfiles. --reload requires watchfiles; without it the flag is silently ignored on some versions.","severity":"breaking","affected_versions":"all"},{"fix":"Use --reload only in development (single process). Use --workers only in production.","message":"--workers and --reload are mutually exclusive. Using both raises an error.","severity":"gotcha","affected_versions":"all"},{"fix":"uvicorn.run('main:app', workers=4) — always use import string with multiple workers.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Expected behavior on Windows. No fix needed, but be aware of performance differences between dev (Windows) and prod (Linux).","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Execute `uvicorn main:app --reload` directly in your shell/terminal, or if calling from a Python script, use `uvicorn.run('main:app', reload=True)`.","message":"The command `uvicorn main:app --reload` is a shell command and cannot be executed directly as Python syntax within a `.py` file. Python will raise a `SyntaxError`. To run uvicorn from a Python script, use `uvicorn.run('main:app', reload=True)`.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure `uvicorn` commands are executed in a shell (e.g., via `subprocess.run()` or a shell script), not parsed directly by the Python interpreter.","message":"Attempting to run `uvicorn` CLI commands (e.g., `uvicorn main:app --reload`) directly within a Python script will lead to a `SyntaxError`, as they are intended for execution in a shell environment.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.42.0':18 '2026':20 '3.10':23 'asgi':5,35 'async':39 'class':27 'current':15 'fast':4 'fastapi':12,37 'gunicorn':25 'lightn':3 'lightning-fast':2 'mar':19 'move':29 'packag':33 'python':8,22 'requir':21 'separ':32 'server':6,10,36 'standard':9 'starlett':14,38 'uvicorn':1 'version':16 'web':34 'worker':26","created_at":"2026-03-25T18:25:50.129121+00:00","updated_at":"2026-04-17T00:07:12.876367+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n  File \"/tmp/tmprztztbpf/venv/lib/python3.12/site-packages/uvicorn/workers.py\", line 10, in <module>\n    from gunicorn.arbiter import Arbiter\nModuleNotFoundError: No module named 'gunicorn'"},"ecosystem":"pypi","meta_description":null,"install_score":80,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.52.4","cli_name":"uvicorn","cli_version":"Running uvicorn 0.47.0 with CPython 3.11.15 on Linux","type":"library","homepage":"https://uvicorn.dev/","github":"https://github.com/sponsors/encode","docs":null,"changelog":"https://uvicorn.dev/release-notes","pypi":"https://pypi.org/project/uvicorn/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-26","next_check":"2026-07-10","install_tag":"verified"}}