jsonl¶

A lightweight, dependency-free Python library for reading, writing, and streaming JSON Lines data.

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 JSON Lines and NDJSON specifications.

Why jsonl?¶

The JSON Lines format is ideal for processing large volumes of structured data line by line, without loading everything into memory. jsonl lets you work with this format effortlessly, offering a familiar API inspired by Python's standard json module — with zero external dependencies.

Features¶

Quick Start¶

Install¶

pip install py-jsonl

Requires Python 3.8 or higher. No external dependencies needed.

Write data¶

import jsonl

data = [
    {"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
    {"name": "May", "wins": []},
]

jsonl.dump(data, "players.jsonl")

Read data¶

import jsonl

for item in jsonl.load("players.jsonl"):
    print(item)

Read from a URL¶

import jsonl

for item in jsonl.load("https://example.com/data.jsonl"):
    print(item)

Compressed files¶

The compression format is detected 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)

Archives (ZIP / TAR)¶

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)

API Overview¶

Reading¶

Writing¶

All write functions accept json_dumps and **json_dumps_kwargs for custom serialization. All read functions accept json_loads and **json_loads_kwargs for custom deserialization.

Supported Formats¶

When reading, if the file extension is not recognized, jsonl falls back to magic-number detection to identify the compression format automatically.

License¶

MIT — see LICENSE for details.