FastAPI gunicorn "Invalid value for --worker-class" (uvicorn worker) in CI

gunicorn was told to run FastAPI with the uvicorn worker class, but it could not import that class. Either uvicorn is not installed in the same environment as gunicorn, or the worker path is misspelled.

What this error means

A gunicorn launch step fails with "gunicorn.errors.HaltServer" or "Invalid value for worker_class: class uri 'uvicorn.workers.UvicornWorker' invalid or not found".

python

gunicorn.errors.ConfigError: class uri 'uvicorn.workers.UvicornWorker'
invalid or not found:

ModuleNotFoundError: No module named 'uvicorn'

Common causes

uvicorn is missing from the gunicorn environment

gunicorn is installed but uvicorn is not, so the worker class it needs to import does not exist.

A misspelled worker class path

The -k value or config does not exactly match uvicorn.workers.UvicornWorker, so gunicorn cannot resolve it.

How to fix it

Install uvicorn alongside gunicorn and use the exact class

Ensure both are installed in the same environment and reference the worker class precisely.

Terminal

python -m pip install gunicorn "uvicorn[standard]"
gunicorn app.main:app -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Pin the worker count and class in config

Declare the worker class in a gunicorn config file so every environment uses the identical value.

gunicorn.conf.py

# gunicorn.conf.py
worker_class = "uvicorn.workers.UvicornWorker"
workers = 2
bind = "0.0.0.0:8000"

How to prevent it

Install gunicorn and uvicorn together in the same environment.
Reference the worker class from a committed gunicorn config, not ad hoc flags.
Smoke-test the gunicorn launch command in CI before deploy.