
TL;DR: One blocking call inside an
async defstalls every coroutine on the loop.asyncio.to_thread()(Python 3.9+) runs that call in a worker thread, so your loop keeps serving requests.
The problem: one blocking call, everyone waits
An event loop runs on a single thread. Coroutines cooperate by hitting await. A blocking call like time.sleep(), requests.get(), or a sync DB driver never yields, so nothing else runs.
async def handler():
time.sleep(3) # the entire loop is frozen for 3 secondsflowchart LR
A(["Request 1"]):::req --> B["time.sleep(3)<br/>BLOCKS THE LOOP"]:::bad
B -.->|"stuck behind it"| C(["Request 2<br/>waiting"]):::wait
B -.->|"stuck behind it"| D(["Request 3<br/>waiting"]):::wait
classDef req fill:#86efac,stroke:#166534,color:#052e16,stroke-width:2px
classDef bad fill:#fca5a5,stroke:#991b1b,color:#450a0a,stroke-width:3px
classDef wait fill:#fde68a,stroke:#92400e,color:#451a03,stroke-width:2pxThe fix: one line
async def handler():
await asyncio.to_thread(time.sleep, 3) # loop stays freeSignature: asyncio.to_thread(func, /, *args, **kwargs). Pass the function and its arguments separately. Don't call it yourself.
What actually happens
to_thread hands your function to the loop's default ThreadPoolExecutor. Your coroutine suspends, the loop keeps working, and the result is delivered back when the thread finishes.
%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#c7d2fe', 'actorBorder': '#4f46e5', 'actorTextColor': '#1e1b4b', 'signalColor': '#4f46e5', 'signalTextColor': '#1e1b4b', 'noteBkgColor': '#fef08a', 'noteTextColor': '#422006', 'noteBorderColor': '#ca8a04'}}}%%
sequenceDiagram
autonumber
participant C as Coroutine
participant L as Event Loop
participant P as Thread Pool
participant W as Worker Thread
rect rgba(59, 130, 246, 0.18)
Note over C,W: Hand off
C->>L: await asyncio.to_thread(fn)
Note over C,L: Coroutine suspends.<br/>Loop is free for other tasks.
L->>P: run_in_executor(None, fn)
P->>W: assign an idle thread
end
rect rgba(249, 115, 22, 0.22)
Note over W: Blocking work<br/>fn() runs here
end
rect rgba(34, 197, 94, 0.2)
Note over C,W: Return
W-->>L: result (thread-safe callback)
L-->>C: resume with the result
endBonus: to_thread copies the current contextvars into the worker. Request IDs, trace IDs, and similar values still work inside the thread.
Proof: three 1-second jobs finish in ~1 second
import asyncio
import time
def blocking_io(n: int) -> str:
time.sleep(1) # stand-in for requests.get, file I/O, a sync SDK...
return f"job {n} done"
async def heartbeat():
for _ in range(2):
print("loop is alive")
await asyncio.sleep(0.5)
async def main():
start = time.perf_counter()
results, _ = await asyncio.gather(
asyncio.gather(*(asyncio.to_thread(blocking_io, i) for i in range(3))),
heartbeat(),
)
print(results, f"in {time.perf_counter() - start:.1f}s") # ≈ 1.0s, not 3s
asyncio.run(main())gantt
title 3 blocking calls × 1s each
dateFormat X
axisFormat %S
tickInterval 1second
section Direct call
job 1 :crit, a1, 0, 1s
job 2 :crit, a2, after a1, 1s
job 3 :crit, a3, after a2, 1s
section to_thread
job 1 :active, b1, 0, 1s
job 2 :active, b2, 0, 1s
job 3 :active, b3, 0, 1sThe heartbeat keeps ticking while all three jobs run, so the loop was never blocked.
The same pattern with a real blocking client
Any sync library works the same way. Here it is with the standard library's HTTP client (swap in requests.get or a sync SDK, and nothing else changes):
import asyncio
import time
import urllib.request
def fetch(url: str) -> int:
with urllib.request.urlopen(url, timeout=10) as resp: # blocking network call
return len(resp.read())
async def main():
urls = ["https://httpbin.org/delay/1"] * 3
start = time.perf_counter()
sizes = await asyncio.gather(*(asyncio.to_thread(fetch, u) for u in urls))
print(sizes, f"in {time.perf_counter() - start:.1f}s") # roughly 1s, not 3s
asyncio.run(main())The FastAPI trap
FastAPI runs a plain def endpoint in an external threadpool, but an async def endpoint runs directly on the event loop. So the classic mistake is marking a handler async def and then calling a sync library inside it.
flowchart LR
R(["Incoming request"]):::req --> H{"Handler style"}:::q
H -->|"async def + blocking call"| X["Runs on the event loop<br/>Every request waits"]:::bad
H -->|"plain def"| T["FastAPI runs it in a threadpool<br/>Loop stays free"]:::good
H -->|"async def + to_thread"| T2["Only the blocking call<br/>moves to a thread"]:::good
classDef req fill:#bae6fd,stroke:#0369a1,color:#082f49,stroke-width:2px
classDef q fill:#ddd6fe,stroke:#5b21b6,color:#2e1065,stroke-width:2px
classDef bad fill:#fca5a5,stroke:#991b1b,color:#450a0a,stroke-width:3px
classDef good fill:#86efac,stroke:#166534,color:#052e16,stroke-width:2px# Bad: blocks the loop for every other request
@app.get("/report")
async def report():
return legacy_client.fetch_report() # sync SDK call
# Fix A: plain def, FastAPI offloads the whole handler
@app.get("/report")
def report():
return legacy_client.fetch_report()
# Fix B: stay async, offload only the blocking call
@app.get("/report")
async def report():
rows = await db.fetch_rows() # async-native call
return await asyncio.to_thread(legacy_client.fetch_report, rows)Pick B when the handler also awaits other things and only one call is blocking.
When should you use it?
flowchart TD
S{{"What's blocking<br/>your event loop?"}}:::q
S -->|"An async-native library exists<br/>(httpx, asyncpg)"| A["Just await it"]:::good
S -->|"Blocking I/O<br/>(requests, files, sync SDKs)"| B["asyncio.to_thread"]:::thread
S -->|"C code that releases the GIL<br/>(hashlib, zlib, numpy)"| B
S -->|"Heavy pure-Python CPU work"| C["ProcessPoolExecutor<br/>via loop.run_in_executor"]:::proc
classDef q fill:#ddd6fe,stroke:#5b21b6,color:#2e1065,stroke-width:2px
classDef good fill:#86efac,stroke:#166534,color:#052e16,stroke-width:2px
classDef thread fill:#7dd3fc,stroke:#075985,color:#082f49,stroke-width:3px
classDef proc fill:#fdba74,stroke:#9a3412,color:#431407,stroke-width:2pxRule of thumb: threads help when the work is waiting (I/O) or runs in C without the GIL. On a standard build, pure-Python number crunching in a thread won't speed up, because only one thread runs Python bytecode at a time, and it competes with your event loop for that lock.
Free-threaded Python: the free-threaded build (no GIL) became officially supported in Python 3.14 (PEP 779), but it is still opt-in, not the default. On those builds, threads can run Python code in parallel. Benchmark to_thread against processes for your own CPU-heavy workload before choosing.
Gotchas
Gotcha | What to do |
|---|---|
Pool is finite. The default is | Cap concurrency with an |
The default executor is shared. | Give heavy or slow jobs a dedicated |
Cancellation doesn't kill the thread. Cancelling the awaiting task stops the | Give blocking calls their own timeouts ( |
Thread safety is on you. Shared mutable state needs locks. | Prefer returning values over mutating globals. |
Don't call asyncio APIs from the worker thread. | Use |
Takeaways
Never block the loop. One sync call can stall every request, in plain asyncio and in FastAPI.
Wrap blocking I/O with
await asyncio.to_thread(fn, *args). It's the simplest fix and the loop stays responsive.Pair it with
asyncio.gatherto run blocking jobs concurrently.Know the limits: the pool is finite and shared, cancellation doesn't stop the thread, and on standard builds the GIL means no CPU speedup. For heavy CPU work, use processes.
Requires Python 3.9+.
Comments(0)
Join the discussion by logging into your account.
No comments yet. Be the first to comment!