jsonl

PyPI Python Coverage License

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.

Install

pip install py-jsonl

Python 3.8+ · No dependencies · Single file

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.
Sequential splitting — divide a stream into fixed-size JSONL files.
Zero dependencies — pure standard library; single .py file you can vendor.

Fully compliant with jsonlines.org and ndjson specs.

API

Reading

Function	Description
`jsonl.load(source, **kw)`	File, URL, or file-like → lazy iterator
`jsonl.open_stream(source, **kw)`	File, URL, or binary file-like → decompressed stream
`jsonl.loads(text, **kw)`	JSON Lines string → lazy iterator
`jsonl.load_archive(file, **kw)`	Unpack JSONL files from ZIP/TAR
`jsonl.loader(stream, broken, **kw)`	Low-level line-stream deserializer

Writing

Function	Description
`jsonl.dump(iterable, file, **kw)`	Write to file (any format)
`jsonl.dumps(iterable, **kw)`	Serialize to string
`jsonl.dump_fork(paths, **kw)`	Write to multiple files at once
`jsonl.dump_archive(path, data, **kw)`	Pack into ZIP/TAR archive
`jsonl.dumper(iterable, **kw)`	Low-level generator → formatted lines

All functions accept cls and **kwargs for custom encoding/decoding.

Full API docs →

Examples

Archives (ZIP / TAR)

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 serializer (orjson)

import orjson
import jsonl

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

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

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

Multiple output files

import jsonl

data = [
    ("a.jsonl", [{"x": 1}]),
    ("b.jsonl", [{"x": 2}]),
    ("a.jsonl", [{"x": 3}]),  # appends to a.jsonl
]
jsonl.dump_fork(data)

Custom encoder/decoder classes

import datetime
import json
import jsonl


class DateEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, datetime.date):
            return obj.isoformat()
        return super().default(obj)


data = [{"event": "launch", "date": datetime.date(2026, 1, 15)}]
jsonl.dump(data, "events.jsonl", cls=DateEncoder)

Command-line interface

Installing the package also provides the jsonl command (equivalently python -m jsonl):

jsonl [OPTIONS] [INFILE] [OUTFILE]

INFILE may be a JSON Lines file, a ZIP/TAR archive, a URL, or - for stdin. When OUTFILE is omitted, output is written to stdout. Processing is streamed and compression is detected automatically.

# Validate and stream a file
jsonl input.jsonl

# Shell pipelines
cat input.jsonl | jsonl --compact > output.jsonl

# Convert compression formats
jsonl input.jsonl.gz output.jsonl.xz

# Read every recognized JSONL/NDJSON member from a ZIP/TAR archive
jsonl dataset.zip > merged.jsonl

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

# Skip invalid records (returns 1 if any are found)
jsonl --broken input.jsonl output.jsonl

# Split into files of 50,000 records; output compression follows the output suffix
jsonl --split 50000 input.jsonl part.jsonl.gz

Useful options include --compact, --sort-keys, --ascii, --member, --broken, and --split. File output is atomic unless --split is used: split files are written incrementally, so files completed before an error remain.

Full command-line documentation

Supported Formats

Type	Extensions
Plain	`.jsonl`
Compressed	`.jsonl.gz` · `.jsonl.bz2` · `.jsonl.xz` · `.jsonl.zst`¹
ZIP	`.zip`
TAR	`.tar` · `.tar.gz` · `.tar.bz2` · `.tar.xz` · `.tar.zst`¹

¹ Requires Python ≥ 3.14

Contributing

See CONTRIBUTING.md for setup, testing, and PR guidelines.

License

MIT

Metadata

Release files for py-jsonl 1.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py-jsonl 1.5.3
File	Size	Uploaded
py_jsonl-1.5.3.tar.gz	35.1 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for py-jsonl 1.5.3
File	Interpreter	ABI	Platform	Reset
py_jsonl-1.5.3-py3-none-any.whl 17.8 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 52.9 kB

Release files / py_jsonl-1.5.3.tar.gz

Download URL	py_jsonl-1.5.3.tar.gz
Size	35.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`4466b9e8422c67c74139efe2981f52d2c4b1ff53fe10bc3b34687d5fbeeae266`
BLAKE2b-256 checksum How to use checksums	`12a553d72a32ea5c3251ecd605084a24bbed9d1be055bad762c2da5df25b04b4`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / py_jsonl-1.5.3-py3-none-any.whl

Download URL	py_jsonl-1.5.3-py3-none-any.whl
Size	17.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`58dc7774b65ba3cc4a84e65acac3ab025c7882c64985f94d0026398d2ac2b4d2`
BLAKE2b-256 checksum How to use checksums	`59ebec4a1fd9cfda2fbe67e477f8ff1162cdd82df49bf011324ce6d7206b4032`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`