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

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_jsonl-1.4.2.tar.gz (19.1 kB view details)

Uploaded Aug 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

py_jsonl-1.4.2-py3-none-any.whl (10.0 kB view details)

Uploaded Aug 4, 2026 Python 3

File details

Details for the file py_jsonl-1.4.2.tar.gz.

File metadata

Download URL: py_jsonl-1.4.2.tar.gz
Upload date: Aug 4, 2026
Size: 19.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for py_jsonl-1.4.2.tar.gz
Algorithm	Hash digest
SHA256	`df9f4fbc8c4689cc15a40ce42a1ed6b73267e365794505ab6f7fb1ac6d01385b`
MD5	`4823786a3234c7f8f6bb854a2b51d9f4`
BLAKE2b-256	`0ee97aecbe798c036f6edfa6e5bf7b60bc76b4804d33afc3e56824eea264c0bb`

See more details on using hashes here.

File details

Details for the file py_jsonl-1.4.2-py3-none-any.whl.

File metadata

Download URL: py_jsonl-1.4.2-py3-none-any.whl
Upload date: Aug 4, 2026
Size: 10.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for py_jsonl-1.4.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`0fa7719d8cbbf255262b35ae46d8866606c9a8b5a69fa992c6926e6dfe6eda7f`
MD5	`1f69ffcd062636b801d5289108fc0393`
BLAKE2b-256	`8f0bc471770d0eb3bb6bc2af2dafebe2d02f35ac26a9d00ebe59dc59e4b386bd`