uvicorn Uvicorn with reload hangs when using a

The Fix

Upgrade to version 0.15.0 or later.

Based on closed Kludex/uvicorn issue #936 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit

@@ -75,6 +75,7 @@ def restart(self) -> None:
 
     def shutdown(self) -> None:
+        self.process.terminate()
         self.process.join()
         message = "Stopping reloader process [{}]".format(str(self.pid))

repro.py

from concurrent.futures import ProcessPoolExecutor
from typing import Any, Dict

from fastapi import FastAPI

app = FastAPI(title="Example API")
POOL = None

@app.on_event("startup")
def startup():
    global POOL
    POOL = ProcessPoolExecutor(max_workers=1)


@app.on_event("shutdown")
def shutdown():
    global POOL
    POOL.shutdown()

def task() -> None:
    """."""
    print("Executed in process pool")


@app.get("/")
def index() -> Dict[str, Any]:
    """Index."""
    POOL.submit(task)
    return {"message": "Hello World"}

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\nUpgrade to version 0.15.0 or later.\nWhen NOT to use: This fix should not be applied if the application relies on persistent processes.\n\n

Why This Fix Works in Production

Trigger: Uvicorn with reload hangs when using a ProcessPoolExecutor
Mechanism: Uvicorn hangs on reload due to the ProcessPoolExecutor not terminating properly
Why the fix works: Addresses the issue where Uvicorn hangs on reload when using a ProcessPoolExecutor by ensuring that processes are terminated before joining them. (first fixed release: 0.15.0).

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

Shows up under Python 3.8.6 in real deployments (not just unit tests).
Uvicorn hangs on reload due to the ProcessPoolExecutor not terminating properly
Production symptom (often without a traceback): Uvicorn with reload hangs when using a ProcessPoolExecutor

Proof / Evidence

GitHub issue: #936
Fix PR: https://github.com/encode/uvicorn/pull/1069
First fixed release: 0.15.0
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.62

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“This is not a bug”

@Kludex · 2022-09-11 · confirmation · source

“incidentally it seems to not happen on #853”

@euri10 · 2021-01-13 · source

“@euri10 thanks. I'll be patient and wait for the MR”

@lukin0110 · 2021-01-13 · source

“Similar issue, probably same root cause: when using a lock to mutate shared state, if the lock is acquired when a reload starts, the new…”

@kellen · 2021-07-29 · source

Failure Signature (Search String)

Uvicorn with reload hangs when using a ProcessPoolExecutor
Uvicorn should reload when file changes are detected.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
Uvicorn with reload hangs when using a ProcessPoolExecutor
Uvicorn should reload when file changes are detected.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
Uvicorn with reload hangs when using a ProcessPoolExecutor
Uvicorn should reload when file changes are detected.

Minimal Reproduction

repro.py

from concurrent.futures import ProcessPoolExecutor
from typing import Any, Dict

from fastapi import FastAPI

app = FastAPI(title="Example API")
POOL = None

@app.on_event("startup")
def startup():
    global POOL
    POOL = ProcessPoolExecutor(max_workers=1)


@app.on_event("shutdown")
def shutdown():
    global POOL
    POOL.shutdown()

def task() -> None:
    """."""
    print("Executed in process pool")


@app.get("/")
def index() -> Dict[str, Any]:
    """Index."""
    POOL.submit(task)
    return {"message": "Hello World"}

Environment

Python: 3.8.6

What Broke

Uvicorn fails to restart after detecting file changes, causing downtime.

Why It Broke

Uvicorn hangs on reload due to the ProcessPoolExecutor not terminating properly

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

Upgrade to version 0.15.0 or later.

When NOT to use: This fix should not be applied if the application relies on persistent processes.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/encode/uvicorn/pull/1069

First fixed release: 0.15.0

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be applied if the application relies on persistent processes.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a stress test that runs high-concurrency workloads and fails on thread dumps / blocked locks.
Enable watchdog dumps in prod (faulthandler, thread dump endpoint) to capture deadlocks quickly.
Make timeouts explicit and test them (unit + integration) to avoid silent behavior changes.
Instrument retries (attempt count + reason) and alert on spikes to catch dependency slowdowns.

Version Compatibility Table

Version	Status
0.15.0	Fixed

Related Issues

No related fixes found.

Cluster: uvicorn:configuration-error All hubs All clusters

Related clusters: Data consistency Race condition SSL handshake

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

uvicorn Uvicorn with reload hangs when using a ProcessPoolExecutor (Fix)