Von Jerry Fan

JSONL in Python: lesen, schreiben und parsen

Ein umfassender Leitfaden für die Arbeit mit JSONL-Dateien (JSON Lines) in Python. Erfahren Sie, wie Sie JSONL-Daten mit Modulen der Standardbibliothek, pandas und besonders schnellen Bibliotheken lesen, schreiben, parsen und streamen.

Warum Python für JSONL?

Python ist die beliebteste Sprache für die Arbeit mit JSONL-Dateien – aus gutem Grund. Mit dem integrierten json-Modul lässt sich JSON ohne zusätzliche Installation parsen, das Iterieren über Dateien ist von Haus aus speichereffizient, und für spezielle Workflows stehen leistungsfähige Bibliotheken wie pandas und orjson bereit. Ob Sie Machine-Learning-Datensätze, Anwendungslogs oder API-Antworten verarbeiten: Python macht Ihnen die Arbeit mit JSONL leicht.

JSONL (JSON Lines) speichert pro Zeile ein JSON-Objekt. Das eignet sich ideal für Streaming, für Logs, an die nur neue Einträge angehängt werden, und für die Verarbeitung großer Datensätze, ohne sie vollständig in den Arbeitsspeicher zu laden. Dazu passt, dass Python Dateien zeilenweise lesen kann. In diesem Leitfaden lernen Sie drei Möglichkeiten zum Lesen und zwei zum Schreiben von JSONL kennen. Außerdem erfahren Sie, wie Sie mit Dateien umgehen, die nicht in den Arbeitsspeicher passen.

JSONL-Dateien in Python lesen

JSONL-Dateien lassen sich in Python auf verschiedene Arten lesen. Welche sich eignet, hängt vom Anwendungsfall ab: Das json-Modul der Standardbibliothek reicht meist aus, pandas erleichtert die Analyse tabellarischer Daten, und Generatoren sind die beste Wahl für große Dateien.

Am einfachsten geht es mit dem integrierten json-Modul von Python: Öffnen Sie die Datei, gehen Sie sie Zeile für Zeile durch und parsen Sie jede Zeile mit json.loads(). Dabei werden alle Datensätze in einer Liste im Arbeitsspeicher gesammelt.

Dateien mit dem json-Modul einlesen
import json


records = []
with open('data.jsonl', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.strip()
        if line:  # Skip empty lines
            records.append(json.loads(line))


print(f'Loaded {len(records)} records')
print(records[0])

Wenn Ihre JSONL-Daten tabellarisch aufgebaut sind, also jeder Datensatz dieselben Schlüssel enthält, kann pandas sie mit einem einzigen Funktionsaufruf direkt in einen DataFrame einlesen. So können Sie besonders schnell mit der Analyse strukturierter JSONL-Daten beginnen.

Lesen mit pandas
import pandas as pd


# Read entire file into a DataFrame
df = pd.read_json('data.jsonl', lines=True)
print(df.head())
print(f'Shape: {df.shape}')


# For large files, read in chunks
chunks = pd.read_json('large.jsonl', lines=True, chunksize=10000)
for chunk in chunks:
    # Process each chunk (DataFrame)
    print(f'Chunk shape: {chunk.shape}')

Verwenden Sie für Dateien, die nicht in den Arbeitsspeicher passen, eine Generatorfunktion. Sie liefert jeweils einen Datensatz und hält so den Speicherverbrauch unabhängig von der Dateigröße konstant. Dieses Vorgehen empfiehlt sich für Datenpipelines im Produktivbetrieb.

Große Dateien mit einem Generator lesen
import json
from typing import Iterator, Any


def read_jsonl(path: str) -> Iterator[dict[str, Any]]:
    """Read a JSONL file lazily, yielding one record at a time."""
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                yield json.loads(line)
            except json.JSONDecodeError as e:
                print(f'Skipping invalid JSON at line {line_num}: {e}')


# Process records one at a time
for record in read_jsonl('large_data.jsonl'):
    process(record)  # Only one record in memory at a time

JSONL-Dateien in Python schreiben

JSONL-Dateien zu schreiben ist einfach: Serialisieren Sie jeden Datensatz als JSON-String und hängen Sie einen Zeilenumbruch an. Dabei gilt: ein JSON-Objekt pro Zeile, ohne abschließende Kommas und ohne umschließendes Array.

Serialisieren Sie jeden Datensatz mit json.dumps() und schreiben Sie das Ergebnis mit einem anschließenden Zeilenumbruch in die Datei. Mit ensure_ascii=False bleiben Unicode-Zeichen wie chinesische und japanische Schriftzeichen oder Emojis in der Ausgabe erhalten.

Dateien mit dem json-Modul schreiben
import json


records = [
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
]


with open('output.jsonl', 'w', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


print(f'Wrote {len(records)} records to output.jsonl')

Wenn Ihre Daten bereits als pandas-DataFrame vorliegen, können Sie sie mit to_json(), orient='records' und lines=True direkt als JSONL exportieren. Das ist der umgekehrte Vorgang zu pd.read_json() mit lines=True.

Schreiben mit pandas
import pandas as pd


df = pd.DataFrame([
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
])


# Write DataFrame to JSONL
df.to_json('output.jsonl', orient='records', lines=True, force_ascii=False)


print(f'Wrote {len(df)} records to output.jsonl')

Python-Bibliotheken für JSONL

Für Python gibt es mehrere Bibliotheken zum Parsen von JSON, die sich in ihrer Performance unterscheiden. Welche am besten passt, hängt von der Dateigröße und Ihren Anforderungen an die Geschwindigkeit ab.

json (stdlib)

Integriert

Das integrierte json-Modul von Python ist ohne Installation überall verfügbar. Für die meisten JSONL-Aufgaben reicht es aus und unterstützt alle JSON-Standardtypen. Bei Dateien bis zu einigen hundert MB ist die Performance ausreichend.

orjson

Schnellste

orjson ist in Rust geschrieben und die schnellste JSON-Bibliothek für Python. Beim Parsen und Serialisieren ist sie gegenüber dem json-Modul der Standardbibliothek 2–10x schneller. Sie gibt Bytes statt Strings aus und unterstützt Dataclasses, datetime, numpy und UUID-Typen nativ.

ujson

Schnell

ujson (UltraJSON) ist eine in C geschriebene JSON-Bibliothek, die 2–5x schneller ist als das json-Modul der Standardbibliothek. Da ihre API nahezu identisch mit der des integrierten json-Moduls ist, lässt sie sich als direkter Ersatz verwenden. Sie bietet einen guten Kompromiss zwischen Kompatibilität und Geschwindigkeit.

Große JSONL-Dateien streamen

Für JSONL-Dateien im Gigabyte-Bereich brauchen Sie einen Streaming-Ansatz, der die Daten blockweise liest, transformiert und schreibt. So bleibt der Speicherverbrauch konstant, und Sie können den Fortschritt verfolgen.

Große JSONL-Dateien streamen
import json
import sys


def process_large_jsonl(
    input_path: str,
    output_path: str,
    batch_size: int = 1000
) -> int:
    """Stream-process a large JSONL file in batches."""
    processed = 0
    batch: list[dict] = []


    with open(input_path, 'r') as fin, \
         open(output_path, 'w') as fout:
        for line in fin:
            line = line.strip()
            if not line:
                continue
            record = json.loads(line)
            # Transform the record
            record['processed'] = True
            batch.append(record)


            if len(batch) >= batch_size:
                for r in batch:
                    fout.write(json.dumps(r) + '\n')
                processed += len(batch)
                batch.clear()
                print(f'\rProcessed {processed} records...', end='')


        # Write remaining records
        for r in batch:
            fout.write(json.dumps(r) + '\n')
        processed += len(batch)


    print(f'\nDone. Processed {processed} records total.')
    return processed


# Usage
process_large_jsonl('input.jsonl', 'output.jsonl', batch_size=5000)

Bei diesem Vorgehen werden Datensätze in Blöcken fester Größe verarbeitet, sodass der Speicherverbrauch konstant bleibt. Mit dem Parameter batch_size bestimmen Sie das Verhältnis zwischen Speicherverbrauch und I/O-Effizienz. Auf den meisten Systemen haben sich Blöcke mit 1.000 bis 10.000 Datensätzen bewährt. Über die Fortschrittsanzeige behalten Sie auch länger laufende Jobs im Blick.

JSONL-Dateien online bearbeiten

Zeigen Sie JSONL-Dateien bis zu 1 GB direkt im Browser an, validieren Sie sie und konvertieren Sie sie in andere Formate. Kein Upload erforderlich, 100 % privat.

Häufig gestellte Fragen

Quellen