Uvicorn

0.42.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install uvicorn

Common errors

error uvicorn.workers.UvicornWorker was moved to a separate package uvicorn-gunicorn-worker ↓

cause The `UvicornWorker` class, used when running Uvicorn under Gunicorn, was deprecated in `uvicorn` and moved to its own `uvicorn-gunicorn-worker` package.

fix

Install the uvicorn-gunicorn-worker package (pip install uvicorn-gunicorn-worker) and update your Gunicorn configuration to use uvicorn_gunicorn_worker.UvicornWorker.

error No application provided. You must specify the application as an importable string in the format "module:attribute". ↓

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.

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.

error OSError: [Errno 98] Address already in use ↓

cause Another process is already listening on the port (default 8000) that Uvicorn is trying to bind to, preventing Uvicorn from starting.

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.

error ModuleNotFoundError: No module named 'your_app_module' ↓

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.

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.

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).

gotcha 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)`. ↓

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)`.

breaking 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. ↓

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.

Install

pip install "uvicorn[standard]"

pip install uvicorn-worker

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) standard - - - -

3.10 alpine (musl) uvicorn - - - -

3.10 alpine (musl) uvicorn-worker - - - 22.1M

3.10 slim (glibc) standard - - - -

3.10 slim (glibc) uvicorn - - - -

3.10 slim (glibc) uvicorn-worker - - - 23M

3.11 alpine (musl) standard - - - -

3.11 alpine (musl) uvicorn - - - -

3.11 alpine (musl) uvicorn-worker - - - 24.4M

3.11 slim (glibc) standard - - - -

3.11 slim (glibc) uvicorn - - - -

3.11 slim (glibc) uvicorn-worker - - - 25M

3.12 alpine (musl) standard - - - -

3.12 alpine (musl) uvicorn - - - -

3.12 alpine (musl) uvicorn-worker - - - 16.1M

3.12 slim (glibc) standard - - - -

3.12 slim (glibc) uvicorn - - - -

3.12 slim (glibc) uvicorn-worker - - - 17M

3.13 alpine (musl) standard - - - -

3.13 alpine (musl) uvicorn - - - -

3.13 alpine (musl) uvicorn-worker - - - 15.8M

3.13 slim (glibc) standard - - - -

3.13 slim (glibc) uvicorn - - - -

3.13 slim (glibc) uvicorn-worker - - - 16M

3.9 alpine (musl) standard - - - -

3.9 alpine (musl) uvicorn - - - -

3.9 alpine (musl) uvicorn-worker - - - 20.5M

3.9 slim (glibc) standard - - - -

3.9 slim (glibc) uvicorn - - - -

3.9 slim (glibc) uvicorn-worker - - - 21M

Imports

UvicornWorker
wrong
```
from uvicorn.workers import UvicornWorker  # removed from uvicorn core
```
correct
```
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
wrong
```
uvicorn.run(app, host='0.0.0.0', port=8000, workers=4)  # app instance with workers fails
```
correct
```
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 stale last tested: 2026-04-23

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