Uvicorn Worker

Uvicorn Worker packages the Gunicorn worker classes that let you run ASGI applications, such as FastAPI and Starlette apps, using Uvicorn under Gunicorn’s process manager. It pairs Uvicorn’s high-performance ASGI server with Gunicorn’s mature process management, so you get graceful restarts, dynamic worker scaling, and zero-downtime upgrades in production.

Previously bundled inside Uvicorn itself, the worker classes were extracted into this standalone package. You reference it via Gunicorn’s -k flag (uvicorn_worker.UvicornWorker), with a UvicornH11Worker variant available for PyPy-compatible deployments.

What You Get

• The UvicornWorker Gunicorn worker class for serving ASGI apps
• A UvicornH11Worker variant for PyPy-compatible deployments using the h11 protocol implementation
• Graceful worker restarts and zero-downtime server upgrades via Gunicorn
• Dynamic control over the number of worker processes with Gunicorn’s -w flag
• A drop-in replacement for the worker classes formerly bundled with Uvicorn

Common Use Cases

• Deploying a FastAPI or Starlette app to production behind Gunicorn with multiple Uvicorn workers
• Running PyPy-compatible ASGI deployments with the pure-Python h11 worker
• Performing zero-downtime restarts and rolling upgrades of an ASGI service

Under The Hood

Architecture - The package’s uvicorn_worker module subclasses Gunicorn’s base worker to define UvicornWorker (and UvicornH11Worker). Each worker translates Gunicorn’s lifecycle callbacks into a Uvicorn Server configured with the target ASGI app, so Gunicorn supervises the process while Uvicorn handles the event loop and HTTP protocol. Configuration such as logging and reloading is documented in the docs/ directory.

Tech Stack - Pure Python, depending on uvicorn and gunicorn. It is packaged with pyproject.toml and documented with MkDocs. The H11 variant swaps Uvicorn’s default httptools-based protocol for the pure-Python h11 implementation to support PyPy.

Code Quality - Despite being tiny, the repo carries a proper tests suite (test_workers.py with a conftest) and a scripts directory for lint, coverage, build, and test, reflecting the encode-ecosystem tooling conventions. It is BSD-3-Clause licensed and versioned.

API Design - There is effectively no application-facing API to learn: users reference the worker class through Gunicorn’s -k flag. This keeps the integration surface to a single command-line string and defers all tuning to Gunicorn and Uvicorn’s own well-documented options.