tomllib vs JSON Config Load: Localhost Lab

Intro — what this post promises

Load equivalent nested app config from TOML via tomllib vs JSON via json. This lab reports loads/s on Linux localhost.

Stdlib tomllib is read-only (no dumps). It is not configparser-vs-json (lab 104) and not json dumps compact/indent (lab 75).

Related links:

• configparser vs json localhost lab
• json dumps compact vs indent localhost lab
• heapq merge vs sorted localhost lab
• islice vs list slice localhost lab
• dataclass replace vs manual localhost lab
• zoneinfo vs utc offset localhost lab
• stat vs path stat localhost lab
• html escape vs manual localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5. Affiliates: 0. Same logical tables/objects in .toml and .json.

Verdict up front (medium ≈ 22 sections / 306 keys, TOML 5260 B / JSON 5917 B): json.loads ~31027.0 loads/s; json.load file ~22155.3; tomllib.loads ~1054.1; tomllib.load file ~1021.4.

Arms

Lab topology

small / medium / large nested tables · 7 rounds · p50
metric: loads/s = 1 / p50_s

Script: lab-evidence/112-tomllib-vs-json/results/run_lab.py.

Lead table — medium (p50)

JSON file load is roughly ~22× tomllib here.

Scale sketch (file load)

TOML vs JSON product tradeoffs

• TOML: comments, dates, human-friendly configs (pyproject.toml style); stdlib can only read.
• JSON: faster parse here; ubiquitous interchange; write with json.dumps; no comments.
• Need to emit TOML from Python? Use a third-party writer — not tomllib.

Write-path reminder

Teams often prototype in TOML then discover they need to serialize overrides at runtime. Budget a writer library early, or keep JSON/YAML for generated overlays while humans still edit a TOML base — this lab only measures load.

Reading it

• Prefer TOML for hand-edited app/tooling config when comments matter.
• Prefer JSON when load rate or machine interchange dominates.
• Do not confuse with INI/configparser (lab 104) or dumps formatting (lab 75).
• Open TOML files binary ("rb") for tomllib.load.

Types and comments

TOML preserves richer literal types (booleans/ints without quotes in our fixture) and allows # comments in real files — JSON does not. That ergonomics win is why pyproject.toml exists even when JSON parses faster on this box. If your config is generated and consumed only by machines, JSON’s speed and dumps symmetry usually win.

vs configparser

Lab 104 compared INI/configparser to JSON. TOML sits closer to JSON’s nested data model while staying human-editable. Do not treat tomllib numbers as interchangeable with configparser numbers — different parsers, different fixtures, different features (interpolation, etc.).

Binary open footgun

tomllib.load requires a binary file object. Passing open(path, "r") raises. Prefer Path.open("rb") or tomllib.loads(path.read_text()) when you already have str text (slightly different decode path — both measured).

Pitfalls

• Expecting tomllib.dumps in stdlib (it does not exist).
• Passing text mode file objects to tomllib.load.
• Comparing against configparser without noting different data models.
• Hot-reloading huge TOML on every request.

Reproduce

python3 lab-evidence/112-tomllib-vs-json/results/run_lab.py

Evidence: summary.json, summary.txt, fixtures/.

Cold-start services that parse config once can ignore the loads/s gap; hot reloaders and per-request overlays should prefer JSON or a cached dict.

Limits

One Linux box. Synthetic nested tables. Not TOML datetime/array-of-tables stress. Not orjson.

Takeaway

On medium nested config, json.load ~22155.3 loads/s beat tomllib.load ~1021.4 loads/s. Pick TOML for editable configs (read-only stdlib), JSON for speed/write path.