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.
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.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 *.jsonl 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

Useful options include --compact, --sort-keys, --ascii, --member, and --broken. File output is atomic: an existing destination is replaced only after the complete input has been processed successfully.

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.0

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.0
File	Size	Uploaded
py_jsonl-1.5.0.tar.gz	27.6 kB	Sep 7, 2026	Details

Built distribution (wheel)

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

Total release size: 42.4 kB

Release files / py_jsonl-1.5.0.tar.gz

Download URL	py_jsonl-1.5.0.tar.gz
Size	27.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`b2f47cf7acf1e4c351bfac9a0245a4ff6d30c26b466cfddac0dc9be375c394ed`
BLAKE2b-256 checksum How to use checksums	`9110b3d1826e607078d57b68393d0c11c9aa05cfd5756782ebe98cb6c1e5a086`
Upload date	Sep 7, 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.0-py3-none-any.whl

Download URL	py_jsonl-1.5.0-py3-none-any.whl
Size	14.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0e90b2ed79fd56b4e6c7b5a01b76820e54262e935ba769aa3eb7333a68c95e2e`
BLAKE2b-256 checksum How to use checksums	`060b780aabe87b0f740b2ba5997cb9c010ea9820f8abd79a17bb1ecf3b0878ef`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`