{"schemaVersion":"1.0","type":"TechArticle","types":["Article","TechArticle"],"slug":"asyncio-to-thread-stop-freezing-your-event-loop-pfbpf","url":"https://zyvop.com/asyncio-to-thread-stop-freezing-your-event-loop-pfbpf","title":"asyncio.to_thread: Stop Freezing Your Event Loop","subtitle":"Run blocking I/O in a worker thread with one line of Python 3.9+, and keep your asyncio event loop fast and responsive.","tldr":"One blocking call inside an async function can freeze every coroutine on your event loop. This post shows how asyncio.to_thread hands that work to a thread pool, with colorful diagrams, a tested demo, a decision guide for threads vs processes, and the gotchas to watch for.","keywords":["backend","concurrency","Python","multithreading","asyncio","Backend"],"entities":["Emma Clements","backend","concurrency","Python","multithreading","asyncio","Backend","ZyVOP"],"keyTakeaways":["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.gather to 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."],"headings":["The problem: one blocking call, everyone waits","The fix: one line","What actually happens","Proof: three 1-second jobs finish in ~1 second","The same pattern with a real blocking client","The FastAPI trap","When should you use it?","Gotchas","Takeaways"],"outboundLinks":["https://peps.python.org/pep-0779/"],"contentText":"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. async def handler(): time.sleep(3) # the entire loop is frozen for 3 secondsflowchart LR A([\"Request 1\"]):::req --&gt; B[\"time.sleep(3)&lt;br/&gt;BLOCKS THE LOOP\"]:::bad B -.-&gt;|\"stuck behind it\"| C([\"Request 2&lt;br/&gt;waiting\"]):::wait B -.-&gt;|\"stuck behind it\"| D([\"Request 3&lt;br/&gt;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-&gt;&gt;L: await asyncio.to_thread(fn) Note over C,L: Coroutine suspends.&lt;br/&gt;Loop is free for other tasks. L-&gt;&gt;P: run_in_executor(None, fn) P-&gt;&gt;W: assign an idle thread end rect rgba(249, 115, 22, 0.22) Note over W: Blocking work&lt;br/&gt;fn() runs here end rect rgba(34, 197, 94, 0.2) Note over C,W: Return W--&gt;&gt;L: result (thread-safe callback) L--&gt;&gt;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) -&gt; 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) -&gt; 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 --&gt; H{\"Handler style\"}:::q H --&gt;|\"async def + blocking call\"| X[\"Runs on the event loop&lt;br/&gt;Every request waits\"]:::bad H --&gt;|\"plain def\"| T[\"FastAPI runs it in a threadpool&lt;br/&gt;Loop stays free\"]:::good H --&gt;|\"async def + to_thread\"| T2[\"Only the blocking call&lt;br/&gt;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&lt;br/&gt;your event loop?\"}}:::q S --&gt;|\"An async-native library exists&lt;br/&gt;(httpx, asyncpg)\"| A[\"Just await it\"]:::good S --&gt;|\"Blocking I/O&lt;br/&gt;(requests, files, sync SDKs)\"| B[\"asyncio.to_thread\"]:::thread S --&gt;|\"C code that releases the GIL&lt;br/&gt;(hashlib, zlib, numpy)\"| B S --&gt;|\"Heavy pure-Python CPU work\"| C[\"ProcessPoolExecutor&lt;br/&gt;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 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 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.gather to 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+.","contentHash":"sha256:a8f4b67677d52eae8d4273e39aed7714b012774bc8419cdf816083394236528b","authorName":"Emma Clements","authorUrl":"https://zyvop.com/author/emma512","authorSameAs":[],"category":"Backend","tags":["backend","concurrency","Python","multithreading","asyncio"],"audience":"Software engineers and developers building applications with Backend","tone":"Practical and evidence-based engineering guidance","readingTimeMinutes":5,"wordCount":1273,"faqs":null,"primaryTopic":"Backend","publishedAt":"2026-11-22T06:27:54.115Z","updatedAt":"2026-11-22T06:27:54.115Z","canonicalUrl":"https://zyvop.com/asyncio-to-thread-stop-freezing-your-event-loop-pfbpf"}