jsonl.load¶

Deserialize a JSON Lines source into an iterator of Python objects. Supports str filenames, URLs, urllib.request.Request objects, and file-like objects.

Function Signature¶

jsonl.load(source, *, opener=None, broken=False, cls=None, **kwargs)

Parameters¶

Parameter	Type	Default	Description
`source`	`str`, `PathLike[str]`, URL, `Request`, file-like	(required)	The JSON Lines source to read from
`opener`	`Callable` or `None`	`None`	Custom function to open the file (not supported for URLs)
`broken`	`bool`	`False`	If `True`, skip malformed lines and log a warning instead of raising an exception
`cls`	`type[json.JSONDecoder]` or `Callable` or `None`	`json.JSONDecoder`	Custom decoder
`**kwargs`			Keyword arguments used to pass the Custom decoder (`cls`)

Returns¶

Iterator[Any] — An iterator yielding deserialized Python objects, one per line.

Compression Detection¶

Note

Supported compression formats: .gz, .bz2, .xz, and .zst (Python ≥ 3.14)

Compression detection depends on the source:

Source	Detection
Local path	Recognized extension, with a magic-number fallback for unknown extensions
Path with `opener=`	Magic bytes from the stream returned by the opener
URL or `Request`	Magic bytes from the response, independently of the URL
Binary file-like object	Magic bytes without requiring `seek()` or consuming bytes from the parsed data
Text file-like object	Assumed to be already decoded and decompressed

If no magic number or recognized extension identifies a supported format, the source is treated as uncompressed. Streams supplied by the caller are never closed by load(); only wrappers created internally for buffering and decompression are closed.

Raw bytes paths and PathLike objects returning bytes are rejected because they are ambiguous with binary content. Decode filesystem paths with os.fsdecode() or wrap binary content in io.BytesIO.

Examples¶

Load from a file path¶

import jsonl

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

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

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

Load from a compressed file¶

import jsonl

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

# Write to a gzip-compressed file
jsonl.dump(data, "file.jsonl.gz")

# Load automatically detects the compression format
for item in jsonl.load("file.jsonl.gz"):
    print(item)

Load from an open file object¶

Tip

Useful when you need to read from a custom source or control how the file is opened.

import jsonl

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

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

with open("file.jsonl") as fp:
    for item in jsonl.load(fp):
        print(item)

Binary file-like objects are inspected for compression without requiring seek support:

import gzip
import io
import jsonl

compressed = gzip.compress(b'{"name": "Alice"}\n')
source = io.BytesIO(compressed)

assert list(jsonl.load(source)) == [{"name": "Alice"}]
assert not source.closed

Load from a URL¶

You can load JSON Lines directly from a remote URL. For custom request headers, use urllib.request.Request:

import urllib.request
import jsonl

# Load directly from a URL
for item in jsonl.load("https://example.com/file.jsonl"):
    print(item)

# Load using a custom request with headers
req = urllib.request.Request(
    "https://example.com/file.jsonl",
    headers={"Accept": "application/jsonl"},
)
for item in jsonl.load(req):
    print(item)

Compression is detected from the response body, so the URL does not need a filename extension:

for item in jsonl.load("https://example.com/download?id=123"):
    print(item)

Handle broken lines¶

Warning

When broken=False (default), an exception is raised on the first malformed line. When broken=True, malformed lines are skipped and a warning is logged.

import jsonl

# Create a file with a broken JSON line
with open("file.jsonl", mode="wt", encoding="utf-8") as fp:
    fp.write('{"name": "Gilbert"}\n')
    fp.write('{"name": "May", "wins": []\n')  # Missing closing brace
    fp.write('{"name": "Richard"}\n')

# Skip broken lines
for item in jsonl.load("file.jsonl", broken=True):
    print(item)

Output:

WARNING:jsonl:Broken line at 2: Expecting ',' delimiter: line 2 column 1 (char 28)
{'name': 'Gilbert'}
{'name': 'Richard'}

Custom deserialization¶

Using a custom JSON Decoder¶

import json

import jsonl


class UpperDecoder(json.JSONDecoder):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, object_hook=self.object_hook, **kwargs)

    def object_hook(self, obj):
        return {k.upper(): v for k, v in obj.items()}


data = [{"name": "Gilbert"}, {"name": "May"}]
jsonl.dump(data, "file.jsonl")

# Read using a custom decoder to convert all keys to uppercase.
for item in jsonl.load("file.jsonl", cls=UpperDecoder):
    print(item)

Using a third-party library¶

orjson is a popular high-performance JSON library:

import orjson
import jsonl

data = [
    {"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
    {"name": "May", "wins": []},
]
jsonl.dump(data, "file.jsonl")

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

Passing keyword arguments¶

Extra keyword arguments are forwarded to the cls decoder.

For example, parse float values as decimal.Decimal:

import decimal
import jsonl

data = [
    {"name": "Gilbert", "wins_avg": 2.5},
    {"name": "May", "wins_avg": 3.75},
]
jsonl.dump(data, "file.jsonl")

for item in jsonl.load("file.jsonl", parse_float=decimal.Decimal):
    print(item)
    # float values are now decimal.Decimal instances

Custom opener¶

The opener parameter lets you control how the file is opened. For example, reading from a ZIP archive:

import zipfile
import jsonl

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

# Create a ZIP archive containing a jsonl file
jsonl.dump(data, "file.jsonl")
with zipfile.ZipFile("data.zip", "w") as zf:
    zf.write("file.jsonl")


def opener(name, *args, **kwargs):
    zf = zipfile.ZipFile(name)
    return zf.open("file.jsonl")


for item in jsonl.load("data.zip", opener=opener):
    print(item)