jsonl
A lightweight, dependency-free Python library for JSON Lines — read, write, compress, and stream with ease.
Documentation · Changelog · Issues
jsonl provides a simple, Pythonic API for working with JSON Lines data.
It follows the conventions of Python's standard json module — if you know json.dump and json.load,
you already know how to use jsonl.
Fully compliant with the jsonlines and ndjson specifications.
| Feature | Description |
|---|---|
| 🌎 Familiar API | Interface similar to the standard json module (dump, load, dumps) |
| ⚡ Streaming by default | Read and write incrementally via iterators, keeping memory usage low |
| 🗜️ Built-in compression | Transparent support for gzip, bzip2, and xz |
| 📦 Archive support | Read and write ZIP and TAR archives (.tar.gz, .tar.bz2, .tar.xz) |
| 📥 Load from URLs | Pass a URL directly to load() or load_archive() |
| 🚀 Pluggable serialization | Swap in orjson, or any JSON library |
| 🔧 Error tolerance | Optionally skip malformed lines instead of crashing |
| 🐍 Zero dependencies | Uses only the Python standard library — nothing else |
pip install py-jsonlRequires Python 3.8+. No external dependencies.
import jsonl
data = [
{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
{"name": "May", "wins": []},
]
jsonl.dump(data, "players.jsonl")import jsonl
for item in jsonl.load("players.jsonl"):
print(item)import jsonl
for item in jsonl.load("https://example.com/data.jsonl"):
print(item)The compression format is determined automatically — by file extension when writing, and by magic numbers when reading if the file extension is not recognized:
import jsonl
data = [{"key": "value"}]
jsonl.dump(data, "file.jsonl.gz") # gzip
jsonl.dump(data, "file.jsonl.bz2") # bzip2
jsonl.dump(data, "file.jsonl.xz") # xz
for item in jsonl.load("file.jsonl.gz"):
print(item)import jsonl
# Write multiple files into an archive
data = [
("users.jsonl", [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]),
("orders.jsonl", [{"id": 1, "total": 99.90}, {"id": 2, "total": 45.00}]),
]
jsonl.dump_archive("data.tar.gz", data)
# Read them back
for filename, items in jsonl.load_archive("data.tar.gz"):
print(f"--- {filename} ---")
for item in items:
print(item)import jsonl
data = [
("file1.jsonl", [{"name": "Alice"}, {"name": "Bob"}]),
("file2.jsonl", [{"name": "Charlie"}]),
("file1.jsonl", [{"name": "Eve"}]), # appended to file1.jsonl
]
jsonl.dump_fork(data)| Function | Description |
|---|---|
jsonl.load(source, **kw) |
Read from a file, URL, or file-like object |
jsonl.load_archive(file, **kw) |
Unpack JSON Lines files from a ZIP or TAR archive |
jsonl.loader(stream, broken, **kw) |
Low-level generator deserializing a line stream |
Tip
All read functions accept json_loads and **json_loads_kwargs for custom deserialization.
| Function | Description |
|---|---|
jsonl.dump(iterable, file, **kw) |
Write objects to a JSON Lines file |
jsonl.dumps(iterable, **kw) |
Serialize to a JSON Lines string |
jsonl.dump_fork(paths, **kw) |
Write to multiple JSON Lines files at once |
jsonl.dump_archive(path, data, **kw) |
Pack multiple JSON Lines files into a ZIP or TAR archive |
jsonl.dumper(iterable, **kw) |
Low-level generator yielding formatted lines |
Tip
All write functions accept json_dumps and **json_dumps_kwargs for custom serialization.
For complete parameter documentation, see the full docs →
Plug in any JSON-compatible serializer. For example, orjson
for high-performance encoding:
import orjson # ensure orjson is installed: pip install orjson
import jsonl
data = [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
# Write with orjson (returns bytes → set text_mode=False)
jsonl.dump(data, "fast.jsonl", json_dumps=orjson.dumps, text_mode=False)
# Read with orjson
for item in jsonl.load("fast.jsonl", json_loads=orjson.loads):
print(item)Extra keyword arguments are forwarded to the underlying serializer:
import jsonl
data = [{"name": "Alice", "score": 9.5}, {"name": "Bob", "score": 7.2}]
jsonl.dump(data, "compact.jsonl", separators=(",", ":")) # compact output
jsonl.dump(data, "sorted.jsonl", sort_keys=True) # deterministic keys| Type | Extensions |
|---|---|
| Plain | .jsonl |
| Compressed | .jsonl.gz, .jsonl.bz2, .jsonl.xz |
| ZIP archive | .zip |
| TAR archive | .tar, .tar.gz, .tar.bz2, .tar.xz |
When reading, if the file extension is not recognized, jsonl falls back to magic-number detection to identify the compression format automatically.
# Install dev dependencies
pip install --group=test --upgrade
# Run tests
python -m pytest tests/
python -m pytest tests/ --cov # run with coverage reporting
# Lint
pip install --group=lint --upgrade
ruff check .
# Docs
pip install --group=doc --upgrade
# zensical usage: https://zensical.org/docs/usage/
zensical build
zensical serveMIT — see LICENSE for details.