py-jsonl 1.3.24

A lightweight Python library for handling jsonlines files.

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.

Features

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

Installation

pip install py-jsonl

Requires Python 3.8+. No external dependencies.

Quick Start

Write

import jsonl

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

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

Read

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 determined automatically — by file extension when writing, and by magic numbers when reading:

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)

Multiple output files

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)

API Overview

Reading

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.

Writing

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 →

Custom Serialization

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

Supported Formats

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.

Contributing

# 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 serve

License

MIT — see LICENSE for details.