jsonl

Zero-dependency Python library for reading, writing, and compressing JSON Lines files.

import jsonl

jsonl.dump([{"name": "Alice"}, {"name": "Bob"}], "file.jsonl.gz")

for item in jsonl.load("file.jsonl.gz"):
    print(item)

If you know json.dump and json.load, you already know jsonl.

Features¶

• Familiar API — same dump/load interface as Python's json module.
• Streaming by default — iterators in, iterators out. Constant memory.
• Automatic compression — .gz, .bz2, .xz, .zst (Python ≥ 3.14). Detected by extension or magic bytes.
• Archive support — read/write .zip, .tar.gz, .tar.bz2, .tar.xz natively.
• URL loading — pass a URL to load() or load_archive() directly.
• Pluggable serialization — swap in orjson, ujson, or any encoder/decoder via cls.
• Error tolerance — skip malformed lines instead of crashing.
• Command-line interface — a json-style jsonl command for shell pipelines.
• Zero dependencies — pure standard library; single .py file you can vendor.

Fully compliant with the JSON Lines and NDJSON specifications.

Quick Start¶

Install¶

pip install py-jsonl

Write and read¶

import jsonl

# Write to plain or compressed files
jsonl.dump([{"name": "Alice"}, {"name": "Bob"}], "users.jsonl")
jsonl.dump([{"key": "value"}], "data.jsonl.gz")

# Read (lazy iterator — constant memory)
for user in jsonl.load("users.jsonl"):
    print(user)

# Read from a URL
for item in jsonl.load("https://example.com/data.jsonl"):
    print(item)

Archives¶

import jsonl

data = [
    ("users.jsonl", [{"name": "Alice"}, {"name": "Bob"}]),
    ("orders.jsonl", [{"id": 1, "total": 99.90}]),
]
jsonl.dump_archive("data.tar.gz", data)

for filename, items in jsonl.load_archive("data.tar.gz"):
    for item in items:
        print(filename, item)

Custom serialization¶

import orjson
import jsonl

data = [{"name": "Alice", "age": 30}]

jsonl.dump(data, "fast.jsonl", text_mode=False, cls=orjson.dumps)

for item in jsonl.load("fast.jsonl", cls=orjson.loads):
    print(item)

Command line¶

Installing the package also provides a jsonl command for shell pipelines:

# Recompress and reformat, streaming from stdin to stdout
cat input.jsonl.gz | jsonl --sort-keys > output.jsonl

# Select members from an archive
jsonl --member '2026/*.jsonl' dataset.tar.gz > output.jsonl

See the Command-line interface page for all options and exit codes.

API Overview¶

Reading¶

Writing¶

Supported Formats¶

¹ Requires Python ≥ 3.14

License¶

MIT — see LICENSE for details.