{"id":470,"date":"2026-07-17T05:04:05","date_gmt":"2026-07-17T05:04:05","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/fastapi-async-2026-def-vs-async-def-the-choice-i-keep-getting-right\/"},"modified":"2026-07-17T05:04:05","modified_gmt":"2026-07-17T05:04:05","slug":"fastapi-async-2026-def-vs-async-def-the-choice-i-keep-getting-right","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/fastapi-async-2026-def-vs-async-def-the-choice-i-keep-getting-right\/","title":{"rendered":"FastAPI Async in 2026: The def vs async def Choice I Keep Getting Right"},"content":{"rendered":"

Short version for the impatient: in FastAPI, async def<\/code> doesn’t make your endpoint faster. It just means “please run me on the event loop, and I promise not to block it”. If you break that promise, one slow request can freeze every other request the worker is handling. If you use plain def<\/code>, FastAPI runs the endpoint in a threadpool and blocking is fine. That’s the whole trick, and I’ve watched senior engineers get it backwards for years.<\/p>\n

I’m writing this because I did an on-call rotation last month where the paging alert was “P99 latency 30 seconds” and the root cause was a single requests.get()<\/code> call sitting inside an async def<\/code> handler. The fix was a one-word edit. The pain was two hours of me squinting at flame graphs first.<\/p>\n

Why async def<\/code> is a promise, not a superpower<\/h2>\n

FastAPI’s routing is a two-tier system, and the official concurrency docs<\/a> spell this out if you read carefully. When you declare a route:<\/p>\n

@app.get("\/thing")\nasync def get_thing():\n    ...\n<\/code><\/pre>\n
FastAPI schedules this on the event loop. That loop is single-threaded per worker. If your handler does anything blocking (a sync HTTP call, a sync DB query, a time.sleep<\/code>, a heavy CPU loop), that entire worker stops serving other requests until it returns.<\/p>\n
Change the signature:<\/p>\n
@app.get("\/thing")\ndef get_thing():\n    ...\n<\/code><\/pre>\n
Now FastAPI runs the function in an anyio threadpool (default 40 threads, tunable via anyio.to_thread.current_default_thread_limiter().total_tokens<\/code>). Blocking calls are fine because the event loop stays free. You lose zero performance for CPU-light endpoints, and you get correctness for free. The anyio threading docs<\/a> explain the exact semantics if you want the underlying model.<\/p>\n
The rule I keep in my head: use async def<\/code> only if every I\/O call inside it is genuinely async<\/strong>. Otherwise use plain def<\/code>. Not “async def because it’s the modern one”. Not “async def because I use FastAPI”. def<\/code> unless you actually mean it.<\/p>\n
The failure mode nobody warns you about<\/h2>\n
Here’s the incident from last month, sanitized. This is the code that shipped:<\/p>\n
import requests\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get("\/user\/{uid}\/profile")\nasync def get_profile(uid: str):\n    # calling a slow internal service\n    r = requests.get(f"http:\/\/users-svc\/internal\/{uid}", timeout=30)\n    return r.json()\n<\/code><\/pre>\n
Under normal load, requests.get<\/code> returned in 40ms and nothing looked wrong. Then the internal users service had a 20-second cold-start after a deploy. Every single in-flight request on that worker queued behind the blocked handler, because requests<\/code> is sync and it froze the event loop. P99 shot to 30 seconds even for \/healthz<\/code>.<\/p>\n
The fix was one of two options:<\/p>\n
# Option A: keep the endpoint sync, let the threadpool handle it\n@app.get("\/user\/{uid}\/profile")\ndef get_profile(uid: str):\n    r = requests.get(f"http:\/\/users-svc\/internal\/{uid}", timeout=30)\n    return r.json()\n<\/code><\/pre>\n
# Option B: go fully async with httpx\nimport httpx\n\n@app.get("\/user\/{uid}\/profile")\nasync def get_profile(uid: str):\n    async with httpx.AsyncClient() as client:\n        r = await client.get(f"http:\/\/users-svc\/internal\/{uid}", timeout=30)\n    return r.json()\n<\/code><\/pre>\n
Option A is a one-word change. Option B is what you want if this endpoint is hot and you’re doing fan-out to several services from the same handler. Both are correct. The half-and-half version I shipped was neither.<\/p>\n
Where async actually pays off<\/h2>\n
I don’t want to give the impression that async def<\/code> is a footgun with no upside. It isn’t. It’s a huge win in three specific shapes:<\/p>\n
Fan-out I\/O.<\/strong> One request needs to hit five services or five DB queries that don’t depend on each other. With async def<\/code> and asyncio.gather<\/code>, you fire them in parallel and wait for the slowest. The threadpool version has to serialize or thread-fan them yourself.<\/p>\n
import asyncio, httpx\n\n@app.get("\/dashboard\/{uid}")\nasync def dashboard(uid: str):\n    async with httpx.AsyncClient() as client:\n        user, orders, notifs = await asyncio.gather(\n            client.get(f"\/users\/{uid}"),\n            client.get(f"\/orders?uid={uid}"),\n            client.get(f"\/notifications?uid={uid}"),\n        )\n    return {"user": user.json(), "orders": orders.json(), "notifs": notifs.json()}\n<\/code><\/pre>\n
Long-lived connections.<\/strong> Websockets, SSE streams, LLM token streaming. The event loop is the correct primitive here. Trying to hold 5,000 threads open for 5,000 open streams will run you out of memory before it runs you out of CPU.<\/p>\n
Background waiting.<\/strong> Anything that spends 99% of its time waiting on the network. An async worker with 4 CPUs will comfortably handle 10,000 concurrent I\/O-bound connections. A threaded worker maxes out around a few hundred before context switching costs eat you.<\/p>\n
A caveat worth calling out: if you’re running FastAPI behind Uvicorn workers and you set --workers 8<\/code> on an 8-core box, each worker has its own event loop and its own threadpool. Blocking one worker doesn’t block the others, so a mixed handler is less catastrophic in production than it looks in a local one-worker test. It’s still wrong, it just fails less loudly.<\/p>\n
If your endpoint doesn’t fit one of those shapes, def<\/code> is almost always the correct choice, and you should stop feeling guilty about it.<\/p>\n
The database question (SQLAlchemy 2.0 makes this easier)<\/h2>\n
The most common trap I see now: async def<\/code> handler + sync SQLAlchemy session. Congratulations, you just moved every DB query onto the event loop with no way for it to yield.<\/p>\n
If you want async endpoints and a real DB, use the async session:<\/p>\n
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession\nfrom sqlalchemy.orm import sessionmaker\n\nengine = create_async_engine("postgresql+asyncpg:\/\/...")\nAsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)\n\nasync def get_session():\n    async with AsyncSessionLocal() as session:\n        yield session\n\n@app.get("\/orders\/{oid}")\nasync def get_order(oid: int, db: AsyncSession = Depends(get_session)):\n    result = await db.execute(select(Order).where(Order.id == oid))\n    return result.scalar_one()\n<\/code><\/pre>\n
SQLAlchemy 2.0’s async API is genuinely nice. It’s the same select\/insert\/update shape as sync, just with await<\/code> on execute<\/code> and commit<\/code>. The SQLAlchemy 2.0 async docs<\/a> are the canonical reference and they don’t hide the sharp edges (no lazy loading, be careful with expire_on_commit<\/code>).<\/p>\n
If you’re not ready to migrate to async DB, keep your endpoint as def<\/code> and use the sync session. That’s a perfectly fine production choice. Don’t mix.<\/p>\n
How I write new endpoints now<\/h2>\n
My mental checklist before writing a new route:<\/p>\n
    \n
  1. List every I\/O call this endpoint will make.<\/strong> DB, HTTP, cache, filesystem, subprocess.<\/li>\n
  2. Is every one of them async-native?<\/strong> (async DB session, httpx.AsyncClient<\/code>, aioredis<\/code>, etc.)<\/li>\n
  3. If yes<\/strong> \u2192 async def<\/code>.<\/li>\n
  4. If no, or you’re not sure<\/strong> \u2192 def<\/code>.<\/li>\n
  5. If it’s mostly CPU work<\/strong> \u2192 def<\/code>, and consider offloading to a Celery worker if it’s heavy.<\/li>\n<\/ol>\n
    That’s it. Five bullets, taped mentally to the inside of my monitor. You don’t need to think harder than this. The rule captures every case I’ve hit in five years of shipping FastAPI, including the ones I got wrong.<\/p>\n
    If you want to sanity-check whether your existing service has the problem, throw asyncio.run(asyncio.sleep(0))<\/code> in your endpoint and load-test it. If a slow endpoint blocks a fast one, you have a mixed handler somewhere. I built a small profiler for this a while back and wrote about it in my post on Postgres full-text search<\/a>, where I hit the same event-loop trap on a search endpoint.<\/p>\n
    What I’d do this week if I inherited a FastAPI codebase<\/h2>\n
    Run this ripgrep in the repo:<\/p>\n
    rg -A 3 'async def' | rg -B 1 -E '(requests\\.|psycopg2|pymysql|time\\.sleep|subprocess\\.run)'\n<\/code><\/pre>\n
    Every match is a place someone put a blocking call inside an async handler. Convert the endpoint to plain def<\/code> or swap the library for an async one. That’s usually an afternoon of work and it will save you a P99 incident.<\/p>\n
    If the codebase is large and you want a longer-term fix, I keep notes on Python backend architecture over on my work page<\/a>. Happy to trade war stories about event loops and threadpools.<\/p>\n","protected":false},"excerpt":{"rendered":"
    In FastAPI, async def is a promise not a superpower. Here’s the def vs async def rule I use, the incident that taught me the hard way, and the code fixes.<\/p>\n","protected":false},"author":2,"featured_media":469,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"In FastAPI, async def is a promise not a superpower. Here's the def vs async def rule I use, the incident that taught me the hard way, and the code fixes.","rank_math_focus_keyword":"fastapi async","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[147,528],"tags":[532,533,531,49,212,529,530,534,535,536],"class_list":["post-470","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-backend","category-python","tag-async-def","tag-async-python","tag-asyncio","tag-backend","tag-concurrency","tag-fastapi","tag-python","tag-sqlalchemy-2","tag-uvicorn","tag-web-framework-2"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/470","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=470"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/470\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/469"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=470"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=470"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=470"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}