Lire du gros JSON en Python, rapidement : benchmark de stdlib, orjson et msgspec
L’essentiel : Le même script de comptage d'étoiles sur du NDJSON prend 754 ms avec la bibliothèque json standard mais seulement 146 ms avec le décodage déclaratif de msgspec, et le parallélisme multicœur ajoute encore un ordre de grandeur. Cet article teste pas à pas stdlib, orjson et msgspec sur un échantillon de 61,4 Mo et 300 000 lignes, et explique d'où vient chaque gain de vitesse et où il s'arrête.

Ce qui ralentit le parsing en Python, ce n'est jamais le texte JSON lui-même, mais le coût de transformation de chaque champ en objet Python. Remplacez le parseur par défaut, construisez moins d'objets, utilisez tous vos cœurs : la même tâche de comptage passe de 0,08 GB/s à des dizaines de GB/s.
Une observation : le même code, un ordre de grandeur d'écart
La tâche est classique : dans un journal NDJSON façon GitHub Events, compter quels dépôts reçoivent le plus d'étoiles parmi les enregistrements dont le type vaut WatchEvent. Sur ma machine (Ubuntu 22.04, Python 3.12, orjson 3.13, msgspec 0.22), j'ai généré un fichier d'échantillon de 61,4 Mo et 300 000 lignes, puis j'ai exécuté quatre implémentations trois fois chacune en gardant le meilleur résultat :
| Implémentation | Meilleur temps | Débit ramené | Relatif |
|---|---|---|---|
json.loads ligne par ligne |
754 ms | 0,08 GB/s | 1× (référence) |
orjson.loads ligne par ligne |
248 ms | 0,24 GB/s | 3,0× |
msgspec décodage en dict |
201 ms | 0,30 GB/s | 3,8× |
msgspec Struct déclaratif |
146 ms | 0,41 GB/s | 5,2× |
Les quatre implémentations ont produit exactement les mêmes comptages d'étoiles (60 108 enregistrements) : toute la différence vient donc du parsing lui-même. Des données tierces confirment ce même ordre de grandeur : dans un benchmark publié par World Programming le 2026-11-14, la même statistique sur 7,6 Go et 2,2 millions d'événements GitHub Archive tournait à 0,28 GB/s avec la bibliothèque standard (environ 27 secondes), environ 8 fois plus vite avec msgspec, tandis que fastsimdjson, basé sur SIMD, a traité tout le jeu de données en 55 ms sur 192 threads (138 GB/s), culminant à 277 GB/s sur un seul fichier. Attention : leur machine est une AWS c8a.metal-48xl à 192 cœurs, ces chiffres ne se transposent pas directement sur un portable — mais la forme de l'échelle reste la même.
Où la bibliothèque standard perd son temps
L'approche json.loads ligne par ligne effectue une « traduction complète » à chaque étape : le parseur balaie {"id": 1, "type": "WatchEvent", ...}, crée un dict neuf, au moins sept objets str et plusieurs int pour ce seul enregistrement, puis passe les références à votre code. Trois cent mille lignes signifient des millions de petites allocations d'objets, dont vous ne touchez jamais la plupart — la tâche de comptage ne lit que deux champs, type et repo.name.
La seconde limite est le GIL. En CPython, un seul thread exécute du bytecode Python à un instant donné, et même si le code C du parseur libère le GIL, votre logique de filtrage et d'accumulation dans la boucle reste séquentielle. Lancer huit threads sur l'interpréteur par défaut ne résout donc rien ; il faut changer d'approche.
Premier palier d'accélération : changez de parseur
C'est l'étape au meilleur rapport gain/effort — la seule modification porte sur l'import :
import json
import orjson
import msgspec
dec = msgspec.json.Decoder()
# Les trois parseurs partagent presque la même interface, sauf dumps :
# orjson.dumps(...) renvoie bytes, pas 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 écrit en Rust, produit directement des octets UTF-8 pendant le parsing et exploite largement les instructions SIMD ; sur ma machine il était trois fois plus rapide. Il y a un piège d'API à retenir : orjson.dumps() renvoie bytes et non str, à gérer lors des écritures de fichiers ou des concaténations.
Le décodage par défaut de msgspec est du même niveau qu'orjson (3,8×), mais sa vraie arme est le décodage déclaratif : il ne construit des objets Python que pour les champs déclarés :
import msgspec
class Event(msgspec.Struct):
type: str
repo: msgspec.Raw # pas encore décodé, octets bruts conservés
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
Dès que repo est déclaré comme msgspec.Raw, les 240 000 lignes sans WatchEvent sautent entièrement la construction de l'objet repo et se contentent de scanner les tokens — c'est exactement là que se joue le passage de 3,8× à 5,2×. Plus un enregistrement a de champs et plus la part jetée est grande, plus ce palier rapporte.
Deuxième palier : découpage multiprocess, à rendement décroissant
Quand un seul cœur est saturé, la réponse classique est le pool de processus : découpez le fichier en N plages d'octets (alignées sur les fins de ligne), confiez chaque tranche à un processus travailleur, puis fusionnez les Counters. Chaque processus ne renvoie qu'une petite table de résultats, donc le coût de communication est minime — la forme idéale du map-reduce.
Le benchmark de World Programming montre à quoi ressemble cette voie : le pool de processus msgspec a culminé à 116 GB/s avec 96 processus, et en ajouter davantage le ralentissait — les coûts d'ordonnancement et de fusion mangeaient le gain. Deux contraintes pratiques s'appliquent : les tranches doivent être alignées sur les sauts de ligne, sinon la dernière ligne de chaque tranche échoue au parsing ; et les tâches de comptage (qui renvoient de petits résultats) sont le meilleur cas pour un pool de processus. Si vous devez extraire et utiliser chaque enregistrement, le transfert entre processus devient lui-même le nouveau goulot.
Troisième palier : SIMD et Python sans GIL
fastsimdjson emprunte une autre route : 8 GB/s sur un seul cœur (environ 3,5 fois msgspec), car il s'appuie sur l'indexation structurée de simdjson — il préscanne la ponctuation pour localiser chaque token sans construire d'arbre d'objets complet ; combiné à fields=["/type", "/repo/name"], il ne lit que les chemins JSON Pointer déclarés, et le callback ne reçoit que ces deux valeurs.
Il est aussi multi-thread : associé au build free-threaded de Python 3.14 (python3.14t, la tentative officielle de la PEP 703 pour supprimer le GIL), 192 threads ont traité 7,6 Go en 55 ms. Sur six fichiers de benchmark publics d'environ 1 Go chacun, quatre ont dépassé 100 GB/s et le plus rapide, le jeu twitter, a atteint 277 GB/s. Gardez en tête que ce sont des re-mesures indépendantes au-delà des annonces du fournisseur, et que l'échantillon est le scénario le plus favorable — « lire un ou deux champs par enregistrement ». Les documents profondément imbriqués n'atteignent pas ces chiffres ; l'un d'eux est resté autour de 20 GB/s.
Tableau de sélection et ordre de déploiement
| Voie | Mécanisme | Débit (local / référence) | Idéal pour |
|---|---|---|---|
json (stdlib) |
construction d'objets complète, un cœur | 0,08 GB/s | petits fichiers, zéro dépendance |
| orjson | Rust + SIMD, construction complète | 0,24 GB/s | remplacement en quelques lignes |
| msgspec dict | Rust, construction complète | 0,30 GB/s | choisir l'un des deux avec orjson |
| msgspec Struct | décode les champs déclarés seulement | 0,41 GB/s | grands tableaux, fort taux d'abandon |
| msgspec multiprocess | parallélisme par tranches | référence 116 GB/s | agrégations, petits résultats |
| fastsimdjson | index structurel + threads | référence 138-277 GB/s | extraction de champs NDJSON, 3.14t |
Un ordre de déploiement sensé : passez d'abord à msgspec ou orjson (quelques minutes de travail pour un 3-5× gratuit) ; si ce n'est pas assez, convertissez les champs du chemin chaud en Struct ; ajoutez un pool de processus pour les tâches de comptage ; n'envisagez fastsimdjson que si vous extrayez des champs ligne par ligne d'un NDJSON et que votre environnement le permet. Si le goulot est la mémoire et non la vitesse — le fichier est trop gros pour être lu en entier — la direction change : passez au streaming ijson, ou à jq --stream en ligne de commande ; voir Traiter du gros JSON en streaming avec jq et Parsing, rendu et streaming de gros JSON. Pour les règles du NDJSON ligne à ligne, voir Le guide pratique des fichiers JSONL.
Discipline de mesure et trois pièges
D'abord, fixez votre méthodologie de chronométrage : dans cet article, chaque implémentation tourne trois fois et on garde le meilleur résultat (pour filtrer le bruit d'ordonnancement), et le fichier est entièrement généré avant le début de la mesure. Quand vous citez des chiffres tiers, indiquez la spécification de la machine — ne comparez jamais 138 GB/s sur 192 cœurs au mono-cœur de votre portable.
Ensuite, validez la correction en croisé : les quatre implémentations ont compté 60 108 étoiles. Toute « accélération » qui change le comptage a changé la sémantique du parsing (gestion des clés dupliquées, précision des grands entiers), pas rendu plus rapide. Alignez d'abord les résultats, ensuite les vitesses.
Enfin, trois pièges classiques : orjson.dumps() renvoie des bytes, et le mélanger avec str produit silencieusement des données sales avec un préfixe b'...' ; les tranches du pool de processus doivent être alignées sur les fins de ligne — après f.seek(offset), jetez d'abord la ligne partielle ; les grands entiers au-delà de 2^53 sont sûrs dans chaque parseur Python, mais si le résultat part vers un côté JavaScript, le problème de précision vous y attend.
FAQ
Faut-il choisir orjson ou msgspec ?
Si vous voulez seulement un loads plus rapide, les deux offrent 3× ou plus — choisissez selon l'activité de maintenance et la familiarité de l'équipe. Choisissez msgspec si vous avez besoin de décodage partiel (msgspec.Struct + Raw), de validation de types ou de sortie TypedDict/dataclass ; son décodage déclaratif ajoute un gain indépendant sur les grands tableaux.
Le multiprocess est-il toujours plus rapide qu'un seul cœur ?
Non. Le découpage, le lancement des processus et la fusion ont des coûts fixes, et avec un fichier de quelques dizaines de Mo c'est souvent une perte. Les tâches qui renvoient de gros résultats (vous avez besoin de chaque enregistrement) perdent leur gain dans le transfert. En règle pratique : changez d'abord de bibliothèque sur un seul cœur, et parallélisez seulement à l'échelle du Go sur des tâches de pur comptage.
Pourquoi mon benchmark orjson ne montre-t-il pas 3× ?
Trois raisons habituelles : l'échantillon est trop petit (le temps de parsing se noie dans la lecture du fichier et le coût de la boucle) ; le vrai goulot est le réseau ou le disque, pas le parsing ; ou les données sont surtout de longues chaînes, donc la part de construction d'objets est faible. Prenez un plus grand échantillon, enveloppez uniquement la boucle de parsing dans time.perf_counter, et concluez ensuite.
Quel est le lien entre ijson et ces bibliothèques ?
ijson est un itérateur en streaming : il sacrifie le débit pour une mémoire constante et convient aux fichiers bien plus gros que la RAM ; orjson/msgspec visent le débit mais transforment chaque enregistrement en objets. Les deux ne se contredisent pas : pour du NDJSON à l'échelle du Go, lire ligne par ligne et décoder vite avec msgspec suffit ; ijson ou jq --stream ne servent que pour un document JSON unique et énorme.