uvicorn

library0.52.4pypypi✓ verified 30d ago

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.

web-framework http-networking

pip install uvicorn

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · UVICORN

uvicorn

web-frameworkpythonv0.52.4

Install

2.5s avg

Import

437ms

Disk

40MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.52.4 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 0.458s · 37.9MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 2.5s · import 0.416s · 42MB

40MB installed

● package 40MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UvicornWorker

✓ from uvicorn.workers import UvicornWorker

✗ from uvicorn.workers import UvicornWorker

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

uvicorn --version

Debug

Known issues

breakingUvicornWorker 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

affects: >= 0.21.0

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

affects: >= 0.32.0

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

affects: >= 0.36.0

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

affects: all

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.

affects: all

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

affects: all

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

affects: all

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

affects: all

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

affects: all

Upgrade

Version history

0.52.4latest on PyPI · released Aug 19, 2026

Audit

Dependencies

uvloopoptionalHigh-performance event loop. Included in uvicorn[standard]. Not available on Windows.

httptoolsoptionalFaster HTTP parser. Included in uvicorn[standard].

watchfilesoptionalRequired for --reload in development. Included in uvicorn[standard].

websocketsoptionalWebSocket support. Included in uvicorn[standard].

uvicorn-workeroptionalProvides UvicornWorker for use with Gunicorn. Moved out of uvicorn core in 0.21.

Agent activity

59 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sponsors/encode ↗

packagehttps://pypi.org/project/uvicorn/ ↗

homepagehttps://uvicorn.dev/ ↗

changeloghttps://uvicorn.dev/release-notes ↗