Skip to main content

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.

Updated 5 min readMarkdown
asyncio.to_thread: Stop Freezing Your Event Loop

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 seconds

Mermaid Diagram


The fix: one line

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 Diagram

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

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 Diagram

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):

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 Diagram

# 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 Diagram

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+.


Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

About the author

  • One platform to write, cross-post to Dev.to, Medium, WordPress, Hashnode, and Bluesky, and protect your SEO with canonical links. Zero paywalls and full content ownership.

No comments yet. Be the first to comment.