--- title: "asyncio.to_thread: Stop Freezing Your Event Loop" author: "Emma Clements" published: "2026-11-22T06:27:54.115Z" updated: "2026-11-22T06:27:54.115Z" url: "https://zyvop.com/asyncio-to-thread-stop-freezing-your-event-loop-pfbpf" canonical: "https://zyvop.com/asyncio-to-thread-stop-freezing-your-event-loop-pfbpf" tags: ["backend","concurrency","Python","multithreading","asyncio"] --- # asyncio.to_thread: Stop Freezing Your Event Loop Run blocking I/O in a worker thread with one line of Python 3.9+, and keep your asyncio event loop fast and responsive. ![Cover image]() > **TL;DR:** One blocking call inside an `async def` stalls _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. ```python async def handler(): time.sleep(3) # the entire loop is frozen for 3 seconds ``` ```mermaid flowchart LR A(["Request 1"]):::req --> B["time.sleep(3)
BLOCKS THE LOOP"]:::bad B -.->|"stuck behind it"| C(["Request 2
waiting"]):::wait B -.->|"stuck behind it"| D(["Request 3
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:2px ``` * * * ## The fix: one line ```python async def handler(): await asyncio.to_thread(time.sleep, 3) # loop stays free ``` Signature: `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. ```mermaid %%{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.
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
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 end ``` Bonus: `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 ```python 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()) ``` ```mermaid 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, 1s ``` The 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): ```python 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. ```mermaid flowchart LR R(["Incoming request"]):::req --> H{"Handler style"}:::q H -->|"async def + blocking call"| X["Runs on the event loop
Every request waits"]:::bad H -->|"plain def"| T["FastAPI runs it in a threadpool
Loop stays free"]:::good H -->|"async def + to_thread"| T2["Only the blocking call
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 ``` ```python # 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? ```mermaid flowchart TD S{{"What's blocking
your event loop?"}}:::q S -->|"An async-native library exists
(httpx, asyncpg)"| A["Just await it"]:::good S -->|"Blocking I/O
(requests, files, sync SDKs)"| B["asyncio.to_thread"]:::thread S -->|"C code that releases the GIL
(hashlib, zlib, numpy)"| B S -->|"Heavy pure-Python CPU work"| C["ProcessPoolExecutor
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:2px ``` **Rule 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 `min(32, cpu_count + 4)` workers (`os.process_cpu_count()` on Python 3.13+). | Cap concurrency with an `asyncio.Semaphore`, or pass your own executor to `loop.run_in_executor`. | | **The default executor is shared.** `to_thread` uses the same pool asyncio uses for `loop.getaddrinfo()` (DNS lookups), so a flood of slow jobs can delay unrelated network calls. | Give heavy or slow jobs a dedicated `ThreadPoolExecutor` with `loop.run_in_executor(my_pool, fn)`. | | **Cancellation doesn't kill the thread.** Cancelling the awaiting task stops the `await`, but the thread runs to completion. | Give blocking calls their own timeouts (`requests.get(..., timeout=10)`). | | **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 `asyncio.run_coroutine_threadsafe(coro, loop)` to talk back to the loop. | * * * ## Takeaways 1. **Never block the loop.** One sync call can stall every request, in plain asyncio and in FastAPI. 2. **Wrap blocking I/O with** `await asyncio.to_thread(fn, *args)`**.** It's the simplest fix and the loop stays responsive. 3. **Pair it with** `asyncio.gather` to run blocking jobs concurrently. 4. **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+._