{"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":[{"note":"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.","wrong":"from uvicorn.workers import UvicornWorker  # removed from uvicorn core","symbol":"UvicornWorker","correct":"from uvicorn_worker import UvicornWorker  # separate package\n# gunicorn app:app -w 4 -k uvicorn_worker.UvicornWorker"},{"note":"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.","wrong":"uvicorn.run(app, host='0.0.0.0', port=8000, workers=4)  # app instance with workers fails","symbol":"uvicorn.run","correct":"uvicorn.run('main:app', host='0.0.0.0', port=8000, workers=4)"}],"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,"last_verified":"2026-05-12T10:04:55.209Z","next_check":"2026-06-25T00:00:00.000Z","problems":[{"fix":"Install the `uvicorn-gunicorn-worker` package (`pip install uvicorn-gunicorn-worker`) and update your Gunicorn configuration to use `uvicorn_gunicorn_worker.UvicornWorker`.","cause":"The `UvicornWorker` class, used when running Uvicorn under Gunicorn, was deprecated in `uvicorn` and moved to its own `uvicorn-gunicorn-worker` package.","error":"uvicorn.workers.UvicornWorker was moved to a separate package uvicorn-gunicorn-worker"},{"fix":"Provide the correct path to your ASGI application in the format `module:attribute`, for example, `uvicorn main:app --reload` where `main.py` contains an `app` instance.","cause":"Uvicorn could not find the ASGI application instance because the command-line argument was missing, malformed, or the specified module/attribute does not exist.","error":"No application provided. You must specify the application as an importable string in the format \"module:attribute\"."},{"fix":"Kill the process using the conflicting port (e.g., `lsof -i :8000` then `kill -9 <PID>`) or run Uvicorn on a different port using `uvicorn main:app --port 8001`.","cause":"Another process is already listening on the port (default 8000) that Uvicorn is trying to bind to, preventing Uvicorn from starting.","error":"OSError: [Errno 98] Address already in use"},{"fix":"Ensure you are running `uvicorn` from the directory containing your application module (e.g., `main.py` for `main:app`), or that the module is correctly installed and accessible on your Python path.","cause":"The Python interpreter cannot find the module specified in the Uvicorn command (e.g., `main:app`), usually because the current directory is not in `sys.path` or the module name is incorrect.","error":"ModuleNotFoundError: No module named 'your_app_module'"}],"ecosystem":"pypi","meta_description":null,"install_score":80,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"22.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"23M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"24.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"25M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"16.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"15.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"16M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"20.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"standard","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"21M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}