UvicornWorker compatibility issues with Python 3.12: worker.nr is always 0, worker.id is missing, and uvicorn-worker dependency is broken

[KaHuier]

Bug Report: UvicornWorker compatibility issues with Python 3.12: worker.nr is always 0, worker.id is missing

Description

I am experiencing several critical issues when running uvicorn.workers.UvicornWorker under Gunicorn on Python 3.13. These issues prevent proper resource allocation (like GPU indexing) in a multi-worker setup because the workers cannot identify their unique index in the pool.

Environment

• OS: Linux (Ubuntu 22.04)
• Python Version: 3.12
• Gunicorn Version: 24.1.1
• Uvicorn Version: 0.40.0
• Uvicorn-worker Version: 0.40.0
• FastAPI Version: 0.116.1
• Installation Method: uv (standard python environment)

---

Issue 1: worker.nr is consistently 0

When using pre_fork or post_fork hooks in Gunicorn to assign resources (e.g., GPU IDs) based on worker.nr, the attribute is always 0 for all workers, even when starting with -w 4.

gunicorn_config.py:

import os

def post_fork(server, worker):
    # This prints '0' for every worker process on Python 3.12
    print(f"[Gunicorn Hook] Worker Index: {worker.nr} | PID: {os.getpid()}")
    os.environ["WORKER_GPU_INDEX"] = str(worker.nr)

Issue 2: worker.id raises AttributeError

Standard Gunicorn workers are expected to have an id attribute, but UvicornWorker throws: AttributeError: 'UvicornWorker' object has no attribute 'id'

Issue 3: Recommended replacement uvicorn-worker is broken

The uvicorn.workers module displays a DeprecationWarning suggesting the use of the uvicorn-worker package. However, installing uvicorn-worker and using -k uvicorn_worker.UvicornWorker fails with: ModuleNotFoundError: No module named 'uvicorn._compat'

Minimal Reproducible Example

1. Create a simple FastAPI app.

2. Define a Gunicorn config with a post_fork hook printing worker.nr.

3. Run the following command:

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -c gunicorn_config.py

4. Observe that all spawned workers report index 0.

Expected Behavior

worker.nr should be a unique, incrementing index (0, 1, 2, 3) for each worker.

worker.id should be accessible as a unique identifier.

The suggested migration path (uvicorn-worker) should be compatible with current Uvicorn releases and Python 3.12.

[murriiii]

These are three separate issues that unfortunately all hit at once. Here are the explanations and workarounds:

Issue 1: worker.nr always 0

This is a Gunicorn 24.x regression/change, not a Uvicorn bug. In Gunicorn 24+, worker.nr was changed to only be set correctly for SyncWorker and GeventWorker. For custom worker classes (which UvicornWorker is), nr defaults to 0.

Workaround — assign GPU index based on spawn order using a shared counter:

# gunicorn_config.py
import os
import multiprocessing

_worker_counter = multiprocessing.Value('i', 0)

def post_fork(server, worker):
    with _worker_counter.get_lock():
        idx = _worker_counter.value
        _worker_counter.value += 1
    os.environ["WORKER_GPU_INDEX"] = str(idx)
    os.environ["CUDA_VISIBLE_DEVICES"] = str(idx)

Alternatively, derive the index from the PID list:

def post_fork(server, worker):
    worker_pids = sorted(w.pid for w in server.WORKERS.values() if w.pid)
    try:
        idx = worker_pids.index(os.getpid())
    except ValueError:
        idx = 0
    os.environ["CUDA_VISIBLE_DEVICES"] = str(idx)

Issue 2: worker.id missing

UvicornWorker inherits from Gunicorn's base Worker class, which has never had a public id attribute. The nr attribute was the intended identifier. Since nr is broken (Issue 1), use the PID-based approach above.

Issue 3: uvicorn-worker package broken

The uvicorn-worker package (separate from uvicorn) hasn't kept up with uvicorn's internal refactoring — specifically, uvicorn._compat was removed. This is a known issue.

Resolution: Keep using uvicorn.workers.UvicornWorker for now despite the deprecation warning. The warning was premature — the uvicorn-worker package isn't ready as a drop-in replacement yet.

To suppress the deprecation warning:

python -W ignore::DeprecationWarning -m gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

Or in your gunicorn config:

import warnings
warnings.filterwarnings("ignore", message=".*uvicorn.workers.*", category=DeprecationWarning)

See also #2798 which discusses the same UvicornWorker vs uvicorn_worker confusion.