Backend

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.

·
4 min read
·
AI-assisted

AI tooling disclosure

Generative AI materially contributed to this article.

Human review confirmed by the author.

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
flowchart 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:2px

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.

%%{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
    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

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

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

Comments(0)

Join the discussion by logging into your account.

No comments yet. Be the first to comment!

Emma Clements

Passionate developer sharing knowledge about modern web technologies and best practices.

Subscribe to Emma Clements's Newsletter

Direct email dispatches when new stories are published. Zero algorithms.