Leer JSON grandes en Python a alta velocidad: pruebas de stdlib, orjson y msgspec
En resumen: El mismo script que cuenta Stars desde NDJSON tarda 754 ms con la biblioteca json estándar pero solo 146 ms con la decodificación declarativa de msgspec, y el paralelismo multinúcleo añade otro orden de magnitud. Este artículo prueba paso a paso stdlib, orjson y msgspec sobre una muestra de 61,4 MB y 300.000 líneas, y explica de dónde nace cada aceleración y dónde se agota.

Lo que ralentiza el análisis en Python nunca es el propio texto JSON, sino el costo de convertir cada campo en un objeto de Python. Cambia el parser por defecto, construye menos objetos, usa todos los núcleos — y la misma tarea de conteo salta de 0,08 GB/s a decenas de GB/s.
Una observación: el mismo código, un orden de magnitud de distancia
La tarea es clásica: en un registro NDJSON al estilo de GitHub Events, contar qué repositorios reciben más estrellas entre los registros cuyo type es WatchEvent. En mi máquina (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22) generé un archivo de muestra de 61,4 MB con 300.000 líneas y ejecuté cuatro implementaciones tres veces cada una, quedándome con el mejor resultado:
| Implementación | Mejor tiempo | Throughput escalado | Relativo |
|---|---|---|---|
json.loads línea a línea |
754 ms | 0,08 GB/s | 1× (base) |
orjson.loads línea a línea |
248 ms | 0,24 GB/s | 3,0× |
msgspec decodificación a dict |
201 ms | 0,30 GB/s | 3,8× |
msgspec Struct declarativo |
146 ms | 0,41 GB/s | 5,2× |
Las cuatro implementaciones produjeron exactamente los mismos conteos de estrellas (60.108 registros), así que toda la diferencia proviene del propio análisis. Datos de terceros respaldan el mismo orden: en una prueba publicada por World Programming el 2026-11-14, la misma estadística sobre 7,6 GB y 2,2 millones de eventos de GitHub Archive corría a 0,28 GB/s con la biblioteca estándar (unos 27 segundos), unas 8 veces más rápido con msgspec, mientras que fastsimdjson, basado en SIMD, terminó todo el conjunto de datos en 55 ms con 192 hilos (138 GB/s), alcanzando 277 GB/s en un solo archivo. Ojo: su máquina es una AWS c8a.metal-48xl con 192 núcleos, así que las cifras no se trasladan directo a un portátil — pero la forma de la escalera es la misma.
Dónde pierde tiempo la biblioteca estándar
El enfoque de json.loads línea a línea hace una "traducción completa" en cada paso: el parser recorre {"id": 1, "type": "WatchEvent", ...}, crea un dict nuevo, al menos siete objetos str y varios int para ese único registro, y luego entrega las referencias a tu código. Trescientas mil líneas significan millones de pequeñas asignaciones de objetos, de las cuales nunca tocas la mayoría — la tarea de conteo solo lee dos campos, type y repo.name.
El segundo límite es la GIL. En CPython solo un hilo ejecuta bytecode de Python en cada instante, y aunque el código C del parser libere la GIL, tu lógica de filtrado y acumulación dentro del bucle sigue siendo serial. Abrir ocho hilos en el intérprete por defecto no soluciona nada; hay que cambiar de estrategia.
Primer peldaño de aceleración: cambia el parser
Es el paso con mejor relación entre resultado y esfuerzo — el único cambio es el import:
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# Los tres parsers comparten casi la misma interfaz, excepto dumps:
# orjson.dumps(...) devuelve bytes, no str
for name, load in [("stdlib", json.loads), ("orjson", orjson.loads), ("msgspec", dec.decode)]:
stars = {}
with open("events.ndjson", "rb") as f:
for line in f:
e = load(line)
if e["type"] == "WatchEvent":
stars[e["repo"]["name"]] = stars.get(e["repo"]["name"], 0) + 1
orjson está escrito en Rust, produce bytes UTF-8 directamente durante el análisis y hace un uso intenso de instrucciones SIMD; en mi máquina fue tres veces más rápido. Hay una trampa de API que conviene recordar: orjson.dumps() devuelve bytes y no str, así que trátalo al escribir archivos o concatenar cadenas.
La decodificación por defecto de msgspec está en la misma clase que orjson (3,8×), pero su arma verdadera es la decodificación declarativa — solo construye objetos de Python para los campos declarados:
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # todavía sin decodificar, se guardan los bytes crudos
dec = msgspec.json.Decoder(Event)
stars = {}
with open("events.ndjson", "rb") as f:
for line in f:
e = dec.decode(line)
if e.type == "WatchEvent":
name = msgspec.json.decode(e.repo)["name"]
stars[name] = stars.get(name, 0) + 1
En cuanto repo se declara como msgspec.Raw, las 240.000 líneas sin WatchEvent saltan por completo la construcción del objeto repo y solo escanean tokens — el salto de 3,8× a 5,2× proviene exactamente de aquí. Cuantos más campos tenga un registro y mayor sea la proporción descartada, más rinde este peldaño.
Segundo peldaño: partición multiproceso, con rendimientos decrecientes
Cuando un núcleo se satura, la respuesta clásica es un pool de procesos: divide el archivo en N rangos de bytes (alineados a los límites de línea), entrega cada porción a un proceso trabajador y al final fusiona los Counters. Cada proceso devuelve solo una tabla pequeña de resultados, así que el costo de comunicación es mínimo — la forma ideal de map-reduce.
El benchmark de World Programming muestra cómo es este camino: el pool de procesos msgspec alcanzó un pico de 116 GB/s con 96 procesos, y añadir más procesos lo ralentizaba — los costos de planificación y fusión se comían la ganancia. Hay dos restricciones prácticas: las porciones deben alinearse con los caracteres de salto de línea, o la última línea de cada porción falla al analizar; y las tareas de conteo (que devuelven resultados pequeños) son el mejor caso para un pool de procesos. Si necesitas extraer y usar cada registro, la propia transferencia entre procesos se convierte en el nuevo cuello de botella.
Tercer peldaño: SIMD y Python sin GIL
fastsimdjson toma otro camino: 8 GB/s en un solo núcleo (unas 3,5 veces msgspec), porque se apoya en la indexación estructurada de simdjson — prescanea la puntuación para localizar cada token sin construir un árbol de objetos completo; combinado con fields=["/type", "/repo/name"] lee solo las rutas JSON Pointer declaradas, y el callback recibe únicamente esos dos valores.
Además es multihilo: combinado con la compilación free-threaded de Python 3.14 (python3.14t, el intento oficial de la PEP 703 de eliminar la GIL), 192 hilos procesaron 7,6 GB en 55 ms. Sobre seis archivos de benchmark públicos de unos 1 GB cada uno, cuatro superaron los 100 GB/s y el más rápido, el conjunto twitter, llegó a 277 GB/s. Ten en cuenta que son mediciones independientes más allá de las afirmaciones del fabricante, y que la muestra es el escenario más favorable — "leer uno o dos campos por registro". Los documentos profundamente anidados no llegan a esas cifras; uno de ellos se quedó en torno a 20 GB/s.
Tabla de elección rápida y orden de adopción
| Vía | Mecanismo | Throughput (local / referencia) | Ideal para |
|---|---|---|---|
json (stdlib) |
construcción completa de objetos, un núcleo | 0,08 GB/s | archivos pequeños, sin dependencias |
| orjson | Rust + SIMD, construcción completa | 0,24 GB/s | reemplazo en pocas líneas |
| msgspec dict | Rust, construcción completa | 0,30 GB/s | elegir uno entre orjson y msgspec |
| msgspec Struct | decodifica solo los campos declarados | 0,41 GB/s | arrays grandes, alto porcentaje de descarte |
| msgspec multiproceso | paralelismo por porciones | referencia 116 GB/s | agregaciones, resultados pequeños |
| fastsimdjson | índice estructural + hilos | referencia 138-277 GB/s | extraer campos de NDJSON, 3.14t |
Un orden de adopción sensato: primero cambia a msgspec u orjson (unos minutos de trabajo por un 3-5× gratis); si no basta, convierte los campos del camino caliente en Struct; para tareas de conteo añade un pool de procesos; considera fastsimdjson solo cuando extraigas campos línea a línea de NDJSON y tu entorno lo permita. Si el cuello de botella es la memoria y no la velocidad — el archivo es demasiado grande para leerlo entero — cambia la dirección: pasa al streaming con ijson, o al jq --stream en línea de comandos; ver Procesar JSON grandes en streaming con jq y Análisis, renderizado y streaming de JSON grandes. Para las reglas línea a línea de NDJSON, ver El manual práctico de archivos JSONL.
Disciplina de medición y tres trampas
Primero, fija la metodología de cronometraje: en este artículo cada implementación corre tres veces y vale el mejor resultado (para filtrar el temblor del planificador), y el archivo está completamente generado antes de empezar la medición. Al citar cifras de terceros, indica la especificación de la máquina — nunca compares 138 GB/s sobre 192 núcleos con un núcleo de tu portátil.
Segundo, valida la corrección en cruz: las cuatro implementaciones contaron 60.108 estrellas. Cualquier "aceleración" que cambia el conteo ha cambiado la semántica del análisis (manejo de claves duplicadas, precisión de enteros grandes), no ha hecho nada más rápido. Alinea primero los resultados, luego las velocidades.
Tercero, tres trampas comunes: orjson.dumps() devuelve bytes, y mezclarlo con str produce en silencio datos sucios con el prefijo b'...'; las porciones del pool de procesos deben alinearse con los límites de línea — tras f.seek(offset), descarta primero la línea incompleta; los enteros grandes por encima de 2^53 son seguros en cualquier parser de Python, pero si el resultado va hacia un lado JavaScript, el problema de precisión ya te espera allí.
FAQ
¿orjson o msgspec, cuál elegir?
Si solo quieres un loads más rápido, ambos dan 3× o más — elige según la actividad de mantenimiento y la familiaridad del equipo. Elige msgspec si necesitas decodificación parcial (msgspec.Struct + Raw), validación de tipos o salida TypedDict/dataclass; su decodificación declarativa añade una ganancia independiente sobre arrays grandes.
¿Multiproceso siempre es más rápido que un núcleo?
No. La división, el lanzamiento de procesos y la fusión tienen costos fijos, y con un archivo de unas decenas de MB suele ser pérdida. Las tareas que devuelven resultados grandes (necesitas cada registro) pierden la ganancia en la transferencia. Como regla práctica: cambia la biblioteca primero en un núcleo, y paraleliza solo a escala de GB en tareas de conteo puro.
¿Por qué mi benchmark de orjson no muestra 3×?
Tres razones habituales: la muestra es demasiado pequeña (el tiempo de análisis se ahoga en la lectura del archivo y el costo del bucle); el cuello de botella real es la red o el disco, no el análisis; o los datos son casi todas cadenas largas, así que la construcción de objetos pesa poco. Usa una muestra mayor, envuelve solo el bucle de análisis en time.perf_counter y solo entonces saca conclusiones.
¿Qué relación tiene ijson con estas bibliotecas?
ijson es un iterador en streaming: sacrifica throughput por memoria constante y sirve para archivos mucho mayores que la RAM; orjson/msgspec persiguen el throughput pero convierten cada registro en objetos. No se contradicen: el NDJSON a escala de GB se resuelve leyendo línea a línea y decodificando rápido con msgspec; ijson o jq --stream solo hacen falta para un único documento JSON enorme.