StackPractices
advanced Por Mathias Paulenko

Guía Completa de Asyncio en Python

Aprende asyncio para cargas reales: coroutines, tasks, event loops, gather, semaphores, queues, clientes HTTP async, websockets y depuración de código async.

Introducción

Asyncio es el framework de Python para escribir código concurrente con la sintaxis async/await. Un solo hilo ejecuta un event loop que hace malabarismos con muchas coroutines: cuando una llega a un await que se bloquearía en I/O —una petición HTTP, una consulta a base de datos, una lectura de socket— se suspende y deja que el loop ejecute otra cosa. Así es como un único proceso asyncio mantiene miles de conexiones abiertas mientras un diseño de un hilo por conexión se queda sin memoria.

Abajo encontrarás coroutines, tasks, el event loop, primitivas de concurrencia, clientes HTTP async, websockets y depuración — en el orden en que de verdad las vas a necesitar. Asume que manejas Python con soltura y usas Python 3.10 o superior. Cuando estos patrones te resulten naturales, el siguiente paso es la guía de producción, que cubre TaskGroup, cancelación, backpressure y observabilidad bajo carga real.

¿Cuándo compensa asyncio de verdad? Trabajo ligado a I/O: llamar APIs externas, lanzar consultas en paralelo, servir conexiones websocket. El trabajo CPU-bound no gana nada con él, y el código que solo hace una llamada bloqueante cada vez tampoco — la complejidad no sale gratis.

Coroutines y async/await

Una coroutine es una función declarada con async def. Llamarla no la ejecuta: devuelve un objeto coroutine que solo corre cuando se espera con await o se programa como task. Esto confunde a todo el mundo la primera semana: fetch_data(url) por sí solo no hace nada más que disparar un RuntimeWarning más tarde.

Dentro de una coroutine, await es a la vez un punto de suspensión y una cesión al event loop. await asyncio.sleep(1) libera el hilo durante un segundo entero; time.sleep(1) lo bloquea y paraliza todas las demás coroutines. Llamadas cooperativas frente a bloqueantes: esa única distinción es el modelo mental sobre el que se construye todo lo demás.

Coroutine básica

import asyncio

async def fetch_data(url: str) -> str:
    print(f"Fetching {url}")
    await asyncio.sleep(1)  # Simula I/O
    return f"Data from {url}"

async def main():
    result = await fetch_data("https://example.com")
    print(result)

asyncio.run(main())

asyncio.run() es el punto de entrada correcto: crea el loop, ejecuta main() hasta el final y cierra todo limpiamente. Solo puedes usarlo una vez por proceso — anidarlo lanza RuntimeError.

Ejecutar varias coroutines secuencialmente

async def main():
    start = asyncio.get_event_loop().time()

    result1 = await fetch_data("https://api1.example.com")
    result2 = await fetch_data("https://api2.example.com")
    result3 = await fetch_data("https://api3.example.com")

    elapsed = asyncio.get_event_loop().time() - start
    print(f"Sequential: {elapsed:.2f}s")  # ~3.0s

Cada await espera a que termine la llamada anterior, así que tres llamadas de un segundo tardan tres segundos. Código secuencial así es una señal de alarma: si no hay dependencia de datos entre las llamadas, deberían correr en paralelo.

Concurrencia con asyncio.gather

async def main():
    start = asyncio.get_event_loop().time()

    results = await asyncio.gather(
        fetch_data("https://api1.example.com"),
        fetch_data("https://api2.example.com"),
        fetch_data("https://api3.example.com"),
    )

    elapsed = asyncio.get_event_loop().time() - start
    print(f"Concurrent: {elapsed:.2f}s")  # ~1.0s
    print(results)

gather() programa las tres coroutines a la vez y devuelve sus resultados en el orden de los argumentos —no en el de finalización—, lo que hace trivial relacionar cada resultado con su entrada. El tiempo total queda igual al de la llamada más lenta, no a la suma de las tres.

Manejo de errores con gather

async def fetch_with_error(url: str) -> str:
    if "error" in url:
        raise ValueError(f"Failed to fetch {url}")
    await asyncio.sleep(0.5)
    return f"Data from {url}"

async def main():
    # return_exceptions=True mantiene los errores como resultados en lugar de lanzarlos
    results = await asyncio.gather(
        fetch_with_error("https://good.example.com"),
        fetch_with_error("https://error.example.com"),
        fetch_with_error("https://good2.example.com"),
        return_exceptions=True,
    )

    for result in results:
        if isinstance(result, Exception):
            print(f"Error: {result}")
        else:
            print(f"Success: {result}")

Sin return_exceptions=True, la primera excepción se propaga y las demás tasks quedan corriendo — una fuente clásica de bugs del tipo “funciona en desarrollo, pierde recursos en producción”. Decide de forma deliberada: fallar rápido con el grupo o recoger errores por task.

Tasks

Un await sobre una coroutine la ejecuta ahí mismo — la ejecución se detiene hasta que termina. Si quieres que arranque de inmediato y consultar el resultado después, envuélvela en una task con asyncio.create_task(). Una task es una coroutine programada en el event loop: empieza a ejecutarse en la siguiente iteración, así que el patrón “crear tasks, hacer otro trabajo, esperar resultados” es donde vive la concurrencia real.

Un detalle que la documentación resta importancia: guarda una referencia a cada task que crees. Como el loop solo guarda una referencia débil, una task que nadie retiene puede ser recolectada por el GC a mitad de ejecución y morir sin avisar.

Crear tasks manualmente

async def main():
    # Programa coroutines como tasks — empiezan a correr inmediatamente
    task1 = asyncio.create_task(fetch_data("https://api1.example.com"))
    task2 = asyncio.create_task(fetch_data("https://api2.example.com"))

    # Haz otro trabajo mientras las tasks corren
    print("Tasks started, doing other work...")
    await asyncio.sleep(0.5)

    # Espera las tasks cuando necesites los resultados
    result1 = await task1
    result2 = await task2
    print(result1, result2)

Cancelación de tasks

async def long_running():
    try:
        while True:
            print("Working...")
            await asyncio.sleep(1)
    except asyncio.CancelledError:
        print("Task cancelled, cleaning up...")
        raise  # Relanza para propagar la cancelación

async def main():
    task = asyncio.create_task(long_running())
    await asyncio.sleep(3.5)
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("Task was cancelled")

task.cancel() lanza CancelledError en el siguiente punto await de la task — no la mata en una instrucción arbitraria. Captúrala, ejecuta tu limpieza y relanza para que la cancelación se propague de verdad. Tragar CancelledError y seguir adelante es el bug de asyncio más común en producción.

Task groups (Python 3.11+)

async def main():
    async with asyncio.TaskGroup() as tg:
        task1 = tg.create_task(fetch_data("https://api1.example.com"))
        task2 = tg.create_task(fetch_data("https://api2.example.com"))
        task3 = tg.create_task(fetch_data("https://api3.example.com"))

    # Todas las tasks completan cuando sale el context manager
    print(task1.result(), task2.result(), task3.result())

Con TaskGroup, si una task falla las demás se cancelan — sin huérfanas — y los errores llegan como ExceptionGroup en vez de perderse. Esos son justo los dos problemas que gather arrastra. En Python 3.11+ debería ser tu opción por defecto; reserva gather para llamadas independientes donde el fallo parcial es aceptable.

El Event Loop

Todo en asyncio gira alrededor de una pieza: el event loop, que no es más que un planificador que controla un solo hilo. Controla exactamente un hilo, ejecuta callbacks y coroutines de una en una, y solo cambia en los puntos await. De ahí se deducen dos reglas: cualquier llamada bloqueante congela todas las coroutines, y el trabajo pesado de CPU entre awaits mata de hambre al resto del loop.

flowchart diagram: coroutine creada

Ejecutar el event loop

# asyncio.run() — recomendado como punto de entrada principal
asyncio.run(main())

# Control manual del loop (para casos avanzados)
async def main():
    loop = asyncio.get_running_loop()
    print(f"Running on: {loop}")

# Correr en un hilo en segundo plano (para mezclar código sync/async)
import asyncio
from threading import Thread

class AsyncRunner:
    def __init__(self):
        self.loop = asyncio.new_event_loop()
        self.thread = Thread(target=self.loop.run_forever, daemon=True)
        self.thread.start()

    def submit(self, coro):
        return asyncio.run_coroutine_threadsafe(coro, self.loop).result()

runner = AsyncRunner()
result = runner.submit(fetch_data("https://example.com"))

AsyncRunner es el puente estándar para llamar código async desde código síncrono — el que acabas escribiendo cuando una base de código sync empieza a necesitar async. run_coroutine_threadsafe es seguro entre hilos; loop.call_soon no lo es.

Semaphores (Limitar la Concurrencia)

Un gather sobre 10.000 URLs significa 10.000 conexiones simultáneas — rápido para ti, un DDoS para la API que llamas. Un semaphore limita cuántas coroutines usan el recurso a la vez; el resto espera su turno. Es la forma más simple de backpressure y la diferencia entre un poller que funciona y uno que te banea la IP.

async def fetch_with_limit(url: str, semaphore: asyncio.Semaphore) -> str:
    async with semaphore:
        await asyncio.sleep(0.5)
        return f"Data from {url}"

async def main():
    semaphore = asyncio.Semaphore(10)  # Máximo 10 concurrentes

    urls = [f"https://api{i}.example.com" for i in range(100)]
    tasks = [fetch_with_limit(url, semaphore) for url in urls]

    results = await asyncio.gather(*tasks)
    print(f"Fetched {len(results)} URLs")

Elige el límite según el rate limit del servicio externo, no tu capacidad local — el cuello de botella casi siempre está del otro lado. Para una receta completa de rate limiting, mira Limitar Operaciones Async con asyncio.Semaphore.

Queues

asyncio.Queue es la versión async de queue.Queue: los productores ponen elementos, los consumidores los sacan, y await gestiona el bloqueo cuando la cola está llena o vacía. Usa maxsize para añadir backpressure — cuando la cola se llena, los productores se suspenden en vez de acumular presión de memoria sin límite.

Patrón productor-consumidor

async def producer(queue: asyncio.Queue, items: list):
    for item in items:
        await queue.put(item)
        print(f"Produced: {item}")
    await queue.put(None)  # Centinela

async def consumer(queue: asyncio.Queue, consumer_id: int):
    while True:
        item = await queue.get()
        if item is None:
            await queue.put(None)  # Pasa el centinela al siguiente consumidor
            break
        await asyncio.sleep(0.5)
        print(f"Consumer {consumer_id} processed: {item}")
        queue.task_done()

async def main():
    queue = asyncio.Queue(maxsize=10)
    items = list(range(20))

    producers = [asyncio.create_task(producer(queue, items))]
    consumers = [asyncio.create_task(consumer(queue, i)) for i in range(3)]

    await asyncio.gather(*producers)
    await queue.join()
    for c in consumers:
        c.cancel()

El patrón centinela (None) es la forma limpia de señalar “no hay más trabajo”. queue.join() espera hasta que cada elemento encolado queda marcado con task_done(), lo que hace explícito el orden de cierre en lugar de confiar en que los consumidores terminen a tiempo.

Clientes HTTP Async

Aquí vive la mayor parte del código asyncio real: llamadas HTTP a APIs y servicios. aiohttp y httpx son las dos opciones serias — httpx tiene la API más agradable y soporta clientes sync y async, aiohttp es madura y algo más rápida en benchmarks. Ambas importan por la misma razón: las conexiones se agrupan por cliente, así que crea uno y reutilízalo en vez de uno por petición. Y nunca uses requests en código async — bloquea todo el loop.

aiohttp

import aiohttp
import asyncio

async def fetch_url(session: aiohttp.ClientSession, url: str) -> dict:
    async with session.get(url) as response:
        return await response.json()

async def fetch_many(urls: list) -> list:
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_url(session, url) for url in urls]
        return await asyncio.gather(*tasks)

async def main():
    urls = [f"https://api.example.com/users/{i}" for i in range(50)]
    results = await fetch_many(urls)
    print(f"Fetched {len(results)} users")

asyncio.run(main())

httpx (sync + async)

import httpx
import asyncio

async def fetch_with_httpx(urls: list) -> list:
    async with httpx.AsyncClient(timeout=30, limits=httpx.Limits(max_connections=20)) as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks)
        return [r.json() for r in responses]

async def main():
    urls = [f"https://api.example.com/items/{i}" for i in range(100)]
    results = await fetch_with_httpx(urls)
    print(f"Got {len(results)} items")

Configura siempre un timeout — un socket que nunca responde colgará una coroutine para siempre. httpx.Limits te da límites de conexiones equivalentes a un semaphore a nivel de cliente.

Reintentos con tenacity

from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
import httpx

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=10),
    retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.RequestError)),
)
async def fetch_with_retry(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.json()

Los reintentos combinan bien con código async — la coroutine se suspende durante el backoff en vez de bloquear un worker. Reintenta solo ante errores transitorios (5xx, timeouts, errores de conexión), nunca ante un 4xx.

Websockets

Los websockets son donde asyncio demuestra su valor: miles de conexiones persistentes en un servidor, sin un hilo por socket. La librería websockets gestiona el protocolo; tú escribes handlers async que parecen coroutines normales.

Servidor

import asyncio
import websockets

connected = set()

async def handler(websocket):
    connected.add(websocket)
    try:
        async for message in websocket:
            # Difunde a todos los clientes conectados
            websockets.broadcast(connected, message)
    finally:
        connected.remove(websocket)

async def main():
    async with websockets.serve(handler, "localhost", 8765):
        await asyncio.Future()  # Corre para siempre

asyncio.run(main())

El registro de conexiones es tuyo; la librería no lo lleva por ti. El finally que quita el websocket importa tanto como la lógica del handler; sáltalo y los sockets muertos se acumulan hasta que el broadcast empiece a fallar.

Cliente

import asyncio
import websockets

async def client():
    uri = "ws://localhost:8765"
    async with websockets.connect(uri) as ws:
        await ws.send("Hello, server!")
        response = await ws.recv()
        print(f"Received: {response}")

asyncio.run(client())

Mezclar Código Sync y Async

Ninguna base de código real llega a ser del todo async. Tendrás una librería bloqueante (boto3, psycopg2, un parser de PDF) que no se puede reemplazar. asyncio.to_thread la ejecuta en un hilo worker para que el loop siga funcionando — no convierte la llamada en no-bloqueante, solo mueve el bloqueo fuera del hilo del loop.

asyncio.to_thread (Python 3.9+)

import asyncio
import time

def blocking_io(duration: float) -> str:
    time.sleep(duration)  # Llamada bloqueante
    return f"Slept for {duration}s"

async def main():
    # Ejecuta la función bloqueante en un hilo
    result = await asyncio.to_thread(blocking_io, 2.0)
    print(result)

asyncio.run(main())

run_in_executor

async def main():
    loop = asyncio.get_running_loop()

    # Usa el thread pool por defecto
    result = await loop.run_in_executor(None, blocking_io, 2.0)

    # Usa un process pool para trabajo CPU-bound
    from concurrent.futures import ProcessPoolExecutor
    with ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, cpu_intensive_work, data)

to_thread es la opción por defecto; recurre a run_in_executor con un ProcessPoolExecutor cuando el trabajo es CPU-bound — los threads siguen compartiendo el GIL. Mira también Thread Pool Executor en Python para la versión puramente síncrona.

asyncio vs threading vs multiprocessing

Elegir el modelo de concurrencia equivocado duele más que cualquier bug de asyncio. La regla general: asyncio para concurrencia I/O-bound en un proceso, threads para código I/O-bound atado a librerías bloqueantes, procesos para trabajo CPU-bound.

asynciothreadingmultiprocessing
Mejor paraI/O de alta concurrenciaI/O con librerías syncTrabajo CPU-bound
Limitado por GILSíSíNo
Coste por taskMuy bajo (~KB)Medio (~8MB stack)Alto (proceso)
Concurrencia práctica+10k conexiones~cientos de threads~núcleos CPU × 2
ComplejidadMedia (disciplina de await)Media (locks, carreras)Alta (IPC, serialización)

Depurar Código Async

Los bugs async fallan en silencio: tasks que nunca corrieron, coroutines nunca esperadas, deadlocks donde todo espera cortésmente a todo lo demás. El kit de depuración es pequeño pero bueno — actívalo todo en desarrollo. Dos herramientas más que ahorran horas: asyncio.all_tasks() lista todas las tasks vivas del loop (útil cuando “algo” impide que el proceso termine), y task.get_stack() / task.print_stack() te muestra exactamente dónde está aparcada una task.

Activar el modo debug

import asyncio
import logging

logging.basicConfig(level=logging.DEBUG)

async def main():
    asyncio.get_running_loop().set_debug(True)

    # Registra callbacks lentos (> 100ms)
    asyncio.get_running_loop().slow_callback_duration = 0.1

    await some_operation()

asyncio.run(main(), debug=True)

El modo debug detecta avisos de never awaited, callbacks que bloquean el loop demasiado tiempo y tasks destruidas pendientes. Combínalo con PYTHONASYNCIODEBUG=1 para activarlo sin tocar código.

Errores habituales

# ERROR 1: Olvidar await — la coroutine nunca corre
async def bad():
    fetch_data("https://example.com")  # ¡Falta await!
    # RuntimeWarning: coroutine 'fetch_data' was never awaited

# ERROR 2: Llamada bloqueante en código async
async def bad():
    time.sleep(5)  # ¡Bloquea todo el event loop!

async def good():
    await asyncio.sleep(5)  # No bloqueante

# ERROR 3: Crear coroutine sin programarla
async def bad():
    coro = fetch_data("https://example.com")
    # Nunca esperada, nunca programada

# ERROR 4: Usar requests (sync) en código async
import requests

async def bad():
    response = requests.get("https://example.com")  # ¡Bloquea el event loop!

async def good():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://example.com")

Buenas Prácticas

  • Usa asyncio.run() como punto de entrada — crea y cierra el event loop correctamente
  • Usa asyncio.gather() para I/O concurrente — ejecuta coroutines en paralelo y espera a todas
  • Limita la concurrencia con semaphores — evita saturar servicios externos
  • Usa asyncio.TaskGroup (3.11+) — mejor manejo de errores que gather
  • Nunca llames funciones bloqueantes en código async — usa asyncio.to_thread() en su lugar
  • Usa clientes HTTP async — aiohttp o httpx, nunca requests
  • Configura timeouts — asyncio.wait_for() o asyncio.timeout() para evitar cuelgues
  • Maneja CancelledError — limpia recursos cuando las tasks se cancelan y relanza la excepción
  • Usa return_exceptions=True cuando quieras gestionar errores por task
  • Prefiere asyncio.Queue sobre threading.Queue — funciona con el event loop
  • Activa el modo debug en desarrollo — detecta awaits olvidados y callbacks lentos
  • Guarda referencias a las tasks creadas — si no, el GC puede cancelarlas a mitad de vuelo

Errores Comunes

  • Olvidar await — la coroutine se crea pero nunca se ejecuta
  • Llamar time.sleep() en vez de await asyncio.sleep() — bloquea el event loop
  • Usar la librería requests en código async — bloquea el event loop
  • No limitar la concurrencia — miles de peticiones simultáneas saturan los servidores
  • Tragar CancelledError sin relanzarlo — la cancelación falla en silencio y el cierre se cuelga
  • Mezclar llamadas a asyncio.run() — solo debe correr un event loop por proceso
  • No configurar timeouts — una respuesta lenta cuelga la aplicación entera
  • Usar asyncio.get_event_loop() en código moderno — usa asyncio.get_running_loop() o asyncio.run()
  • Crear tasks sin guardar referencias — el recolector de basura puede cancelarlas
  • No usar async with para recursos — las conexiones se pierden sin limpieza adecuada

See Also

Preguntas frecuentes

¿Cuándo uso asyncio vs threading vs multiprocessing?

Usa asyncio para cargas I/O-bound (peticiones HTTP, consultas a bases de datos, I/O de archivos) — maneja miles de conexiones concurrentes en un solo hilo. Usa threading para código I/O-bound atado a librerías bloqueantes como requests o boto3. Usa multiprocessing para trabajo CPU-bound, ya que el GIL impide que asyncio y los threads usen varios núcleos.

¿Puedo usar asyncio con Flask?

Flask es síncrono de fondo. Desde la 2.0 acepta vistas async def, pero corren en un hilo worker con concurrencia limitada — compatibilidad, no async real. Para manejo de peticiones respaldado por asyncio de verdad, vete a FastAPI, Quart o Starlette.

¿Cómo pruebo código async?

La vía limpia es pytest-asyncio, que te permite escribir funciones de test async directamente:

import pytest

@pytest.mark.asyncio
async def test_fetch_data():
    result = await fetch_data("https://example.com")
    assert "Data from" in result
¿Qué pasa si olvido await en una coroutine?

No pasa nada — que es justo el problema. Obtienes un objeto coroutine que nunca corre, más un RuntimeWarning: coroutine was never awaited en algún momento posterior, lejos del bug real. Activa el modo debug de asyncio y trata los warnings como errores en CI.

¿Es asyncio más rápido que threading?

A escala de I/O, sí: una coroutine cuesta unos KB frente a ~8MB de stack por thread, y un solo loop hace malabarismos con decenas de miles de conexiones donde unos cientos de threads se comerían la memoria. Con poca concurrencia o trabajo CPU-bound la ventaja desaparece — y los threads son más simples.

¿Puedo anidar asyncio.run() o llamarlo desde un notebook Jupyter?

No. Un loop por hilo — asyncio.run() dentro de un loop activo lanza RuntimeError. Jupyter ya mantiene el suyo corriendo, por eso el await de nivel superior funciona en notebooks. En scripts, quédate con un único punto de entrada asyncio.run().

¿Cómo detengo una task colgada?

task.cancel() entrega CancelledError en el siguiente await de la task. Una task aparcada en una llamada bloqueante — o una coroutine que nunca hace await — no puede ser alcanzada, y por eso asyncio.wait_for(task, timeout) junto a librerías async nativas importa más que la cancelación en sí.