Ler JSON grande em Python com velocidade: benchmark de stdlib, orjson e msgspec
Resumo: O mesmo script de contagem de Stars em NDJSON leva 754 ms com a biblioteca json padrão e apenas 146 ms com a decodificação declarativa do msgspec, e o paralelismo multinúcleo adiciona mais uma ordem de grandeza. Este artigo testa passo a passo stdlib, orjson e msgspec em uma amostra de 61,4 MB e 300.000 linhas, explicando de onde vem cada aceleração e quando ela se esgota.

O que deixa o parsing em Python lento nunca é o próprio texto JSON, e sim o custo de transformar cada campo em um objeto Python. Troque o parser padrão, construa menos objetos, use todos os núcleos — e a mesma tarefa de contagem salta de 0,08 GB/s para dezenas de GB/s.
Uma observação: o mesmo código, um ordem de grandeza de diferença
A tarefa é clássica: em um log NDJSON no estilo GitHub Events, contar quais repositórios recebem mais estrelas entre os registros cujo type é WatchEvent. Na minha máquina (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22), gerei um arquivo de amostra de 61,4 MB com 300.000 linhas e executei quatro implementações três vezes cada, guardando o melhor resultado:
| Implementação | Melhor tempo | Throughput proporcional | Relativo |
|---|---|---|---|
json.loads linha a linha |
754 ms | 0,08 GB/s | 1× (base) |
orjson.loads linha a linha |
248 ms | 0,24 GB/s | 3,0× |
msgspec decodificando para dict |
201 ms | 0,30 GB/s | 3,8× |
msgspec Struct declarativo |
146 ms | 0,41 GB/s | 5,2× |
As quatro implementações produziram exatamente as mesmas contagens de estrelas (60.108 registros), então toda a diferença vem do próprio parsing. Dados de terceiros confirmam a mesma ordem de grandeza: em um benchmark publicado pela World Programming em 2026-11-14, a mesma estatística sobre 7,6 GB e 2,2 milhões de eventos do GitHub Archive rodava a 0,28 GB/s com a biblioteca padrão (cerca de 27 segundos), cerca de 8 vezes mais rápido com msgspec, enquanto o fastsimdjson, baseado em SIMD, processou todo o conjunto em 55 ms em 192 threads (138 GB/s), chegando a 277 GB/s em um único arquivo. Atenção: a máquina deles é uma AWS c8a.metal-48xl com 192 núcleos, então esses números não se transferem direto para um notebook — mas o formato da escada é o mesmo.
Onde a biblioteca padrão perde tempo
A abordagem de json.loads linha a linha faz uma "tradução completa" em cada etapa: o parser varre {"id": 1, "type": "WatchEvent", ...}, cria um dict novo, pelo menos sete objetos str e vários int para aquele único registro, e depois entrega as referências ao seu código. Trezentas mil linhas significam milhões de pequenas alocações de objetos, e você nunca toca na maioria delas — a tarefa de contagem lê apenas dois campos, type e repo.name.
O segundo limite é a GIL. No CPython, apenas uma thread executa bytecode Python por vez, e mesmo que o código C do parser libere a GIL, sua lógica de filtro e acumulação dentro do loop continua serial. Abrir oito threads no interpretador padrão não resolve nada; é preciso mudar a estratégia.
Primeiro nível de aceleração: troque o parser
É o passo com melhor custo-benefício — a única mudança é o import:
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# Os três parsers compartilham quase a mesma interface, exceto dumps:
# orjson.dumps(...) retorna bytes, não 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
O orjson é escrito em Rust, produz bytes UTF-8 diretamente durante o parsing e faz uso intenso de instruções SIMD; na minha máquina ele foi três vezes mais rápido. Há uma armadilha de API que vale lembrar: orjson.dumps() retorna bytes e não str, então trate isso ao gravar arquivos ou concatenar strings.
A decodificação padrão do msgspec está no mesmo nível do orjson (3,8×), mas sua arma verdadeira é a decodificação declarativa — ela constrói objetos Python apenas para os campos declarados:
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # ainda não decodificado, bytes crus mantidos
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
Assim que repo é declarado como msgspec.Raw, as 240.000 linhas sem WatchEvent pulam completamente a construção do objeto repo e apenas escaneiam tokens — é exatamente daí que vem o salto de 3,8× para 5,2×. Quanto mais campos tem um registro e maior a proporção descartada, maior o ganho desse passo.
Segundo nível: fragmentação multiprocesso, com ganhos decrescentes
Quando um único núcleo satura, a resposta clássica é um pool de processos: divida o arquivo em N faixas de bytes (alinhadas às fronteiras de linha), entregue cada fatia a um processo trabalhador e mescle os Counters no final. Cada processo devolve apenas uma pequena tabela de resultados, então o custo de comunicação é mínimo — a forma ideal de map-reduce.
O benchmark da World Programming mostra como esse caminho se comporta: o pool de processos msgspec atingiu o pico de 116 GB/s com 96 processos, e adicionar mais processos o deixava mais lento — os custos de escalonamento e mesclagem consumiam o ganho. Duas restrições práticas se aplicam: as fatias devem estar alinhadas aos caracteres de nova linha, senão a última linha de cada fatia falha no parsing; e tarefas de contagem (que devolvem resultados pequenos) são o melhor caso para um pool de processos. Se você precisa extrair e usar cada registro, a própria transferência entre processos se torna o novo gargalo.
Terceiro nível: SIMD e Python sem GIL
O fastsimdjson segue outro caminho: 8 GB/s em um único núcleo (cerca de 3,5 vezes o msgspec), porque se apoia na indexação estruturada do simdjson — ele pré-escaneia a pontuação para localizar cada token sem construir uma árvore completa de objetos; combinado com fields=["/type", "/repo/name"], lê apenas os caminhos JSON Pointer declarados, e o callback recebe somente esses dois valores.
Ele também é multithread: combinado com o build free-threaded do Python 3.14 (python3.14t, a tentativa oficial da PEP 703 de remover a GIL), 192 threads processaram 7,6 GB em 55 ms. Em seis arquivos públicos de benchmark de cerca de 1 GB cada, quatro ultrapassaram 100 GB/s e o mais rápido, o dataset twitter, alcançou 277 GB/s. Lembre que essas são remedições independentes além das afirmações do fornecedor, e que a amostra é o cenário mais favorável — "ler um ou dois campos por registro". Documentos profundamente aninhados não chegam a esses números; um deles ficou perto de 20 GB/s.
Tabela de escolha rápida e ordem de adoção
| Caminho | Mecanismo | Throughput (local / referência) | Melhor para |
|---|---|---|---|
json (stdlib) |
construção total de objetos, um núcleo | 0,08 GB/s | arquivos pequenos, zero dependências |
| orjson | Rust + SIMD, construção total | 0,24 GB/s | substituição em poucas linhas |
| msgspec dict | Rust, construção total | 0,30 GB/s | escolher um entre orjson e msgspec |
| msgspec Struct | decodifica só os campos declarados | 0,41 GB/s | arrays grandes, alta taxa de descarte |
| msgspec multiprocesso | paralelismo por fatias | referência 116 GB/s | agregações, conjuntos de resultados pequenos |
| fastsimdjson | índice estrutural + threads | referência 138-277 GB/s | extração de campos de NDJSON, 3.14t |
Uma ordem de adoção sensata: primeiro troque para msgspec ou orjson (poucos minutos de trabalho por um 3-5× de graça); se não bastar, converta os campos do caminho quente em Struct; adicione um pool de processos para tarefas de contagem; considere fastsimdjson apenas quando extrair campos linha a linha de NDJSON e seu ambiente permitir. Se o gargalo é memória e não velocidade — o arquivo é grande demais para ler inteiro — a direção muda: passe para o streaming com ijson, ou para o jq --stream na linha de comando; veja Processar JSON grande em streaming com jq e Parsing, renderização e streaming de JSON grande. Para as regras de NDJSON linha a linha, veja O manual prático de arquivos JSONL.
Disciplina de medição e três armadilhas
Primeiro, fixe sua metodologia de cronometragem: neste artigo cada implementação roda três vezes e vale o melhor resultado (para filtrar a oscilação do agendador), e o arquivo está totalmente gerado antes do início da medição. Ao citar números de terceiros, indique a especificação da máquina — nunca compare 138 GB/s em 192 núcleos com um núcleo do seu notebook.
Segundo, valide a corretude em cruzamento: as quatro implementações contaram 60.108 estrelas. Qualquer "aceleração" que mude a contagem alterou a semântica do parsing (tratamento de chaves duplicadas, precisão de inteiros grandes), não ficou mais rápida. Alinhe primeiro os resultados, depois as velocidades.
Terceiro, três armadilhas comuns: orjson.dumps() retorna bytes, e misturá-lo com str produz silenciosamente dados sujos com o prefixo b'...'; as fatias do pool de processos devem estar alinhadas às fronteiras de linha — após f.seek(offset), descarte primeiro a linha parcial; inteiros grandes acima de 2^53 são seguros em qualquer parser Python, mas se o resultado vai para o lado JavaScript, o problema de precisão o espera lá.
FAQ
Devo escolher orjson ou msgspec?
Se você só quer um loads mais rápido, ambos entregam 3× ou mais — escolha pela atividade de manutenção e pela familiaridade da equipe. Escolha o msgspec quando precisar de decodificação parcial (msgspec.Struct + Raw), validação de tipos ou saída TypedDict/dataclass; sua decodificação declarativa adiciona um ganho independente em arrays grandes.
Multiprocesso é sempre mais rápido que um núcleo?
Não. Divisão, inicialização de processos e mesclagem têm custos fixos, e com um arquivo de algumas dezenas de MB geralmente dá prejuízo. Tarefas que devolvem resultados grandes (você precisa de cada registro) perdem o ganho na transferência. Como regra prática: troque a biblioteca primeiro em um núcleo, e paralelize só na escala de GB em tarefas de pura contagem.
Por que meu benchmark do orjson não mostra 3×?
Três razões comuns: a amostra é pequena demais (o tempo de parsing se afoga na leitura do arquivo e no custo do loop); o gargalo real é rede ou disco, não o parsing; ou os dados são quase todos strings longas, então a construção de objetos tem peso pequeno. Use uma amostra maior, envolva apenas o loop de parsing em time.perf_counter e só então conclua.
Qual é a relação do ijson com essas bibliotecas?
O ijson é um iterador em streaming: ele sacrifica throughput por memória constante e serve para arquivos muito maiores que a RAM; orjson/msgspec buscam throughput mas transformam cada registro em objetos. Os dois não conflitam: NDJSON na escala de GB se resolve lendo linha a linha com decodificação rápida do msgspec; ijson ou jq --stream só é necessário para um único documento JSON enorme.