JSONL w Python: Czytanie, zapis i parsowanie

Kompletny przewodnik pracy z plikami JSONL (JSON Lines) w Python. Naucz się czytać, zapisywać, parsować i strumieniować dane JSONL przy użyciu wbudowanych modułów, pandas i wysokowydajnych bibliotek.

Ostatnia aktualizacja: luty 2026

Dlaczego Python do JSONL?

Python jest najpopularniejszym językiem do pracy z plikami JSONL, i to nie bez powodu. Jego wbudowany moduł json obsługuje parsowanie JSON od razu po instalacji, iteracja po plikach jest domyślnie wydajna pamięciowo, a ekosystem oferuje potężne biblioteki takie jak pandas i orjson do specjalistycznych zastosowań. Niezależnie od tego, czy przetwarzasz zbiory danych uczenia maszynowego, logi aplikacji czy odpowiedzi API, Python sprawia, że obsługa JSONL jest prosta.

JSONL (JSON Lines) przechowuje jeden obiekt JSON na linię, co czyni go idealnym do strumieniowania, logowania w trybie append-only i przetwarzania dużych zbiorów danych bez ładowania wszystkiego do pamięci. Czytanie plików linia po linii w Python doskonale pasuje do tego formatu. W tym przewodniku poznasz trzy podejścia do czytania JSONL, dwa podejścia do zapisu oraz sposób obsługi plików zbyt dużych, by zmieścić się w pamięci.

Czytanie plików JSONL w Python

Istnieje kilka sposobów czytania plików JSONL w Python, każdy odpowiedni do innych przypadków użycia. Standardowy moduł json sprawdza się w większości scenariuszy, pandas jest wygodny do analizy tabelarycznej, a generatory najlepiej nadają się do dużych plików.

Najprostsze podejście wykorzystuje wbudowany moduł json Python. Otwórz plik, iteruj linia po linii i parsuj każdą linię za pomocą json.loads(). To ładuje wszystkie rekordy do listy w pamięci.

Podstawowe czytanie z modułem json
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])

Jeśli dane JSONL są tabelaryczne (te same klucze w każdym rekordzie), pandas może je wczytać bezpośrednio do DataFrame jednym wywołaniem funkcji. To najszybszy sposób na rozpoczęcie analizy ustrukturyzowanych danych JSONL.

Czytanie z 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}')

Dla plików zbyt dużych, by zmieścić się w pamięci, użyj funkcji generatora. Zwraca ona jeden rekord naraz, utrzymując stałe zużycie pamięci niezależnie od rozmiaru pliku. Jest to zalecany wzorzec dla produkcyjnych potoków danych.

Wzorzec generatora dla dużych plików
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

Zapis plików JSONL w Python

Zapis plików JSONL jest prosty: serializuj każdy rekord jako ciąg JSON i dodaj znak nowej linii. Kluczowa zasada to jeden obiekt JSON na linię, bez końcowych przecinków ani otaczającej tablicy.

Użyj json.dumps() do serializacji każdego rekordu, a następnie zapisz go z następującym znakiem nowej linii. Ustaw ensure_ascii=False, aby zachować znaki Unicode, takie jak polskie, japońskie czy emoji w danych wyjściowych.

Podstawowy zapis z modułem json
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')

Jeśli dane są już w pandas DataFrame, użyj to_json() z orient='records' i lines=True, aby wyeksportować je bezpośrednio jako JSONL. Jest to odwrotność pd.read_json() z lines=True.

Zapis z 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')

Biblioteki Python do JSONL

Python oferuje kilka bibliotek parsowania JSON o różnych charakterystykach wydajności. Wybór odpowiedniej zależy od rozmiaru pliku i wymagań wydajnościowych.

json (stdlib)

Wbudowany

Wbudowany moduł json Python nie wymaga instalacji i działa wszędzie. Jest wystarczający dla większości zastosowań JSONL i obsługuje wszystkie standardowe typy JSON. Wydajność jest odpowiednia dla plików do kilkuset MB.

orjson

Najszybszy

orjson jest najszybszą biblioteką JSON Python, napisaną w Rust. Zapewnia 2-10x szybsze parsowanie i serializację w porównaniu ze standardowym modułem json. Zwraca bajty zamiast ciągów znaków i natywnie obsługuje dataclasses, datetime, numpy i typy UUID.

ujson

Szybki

ujson (UltraJSON) to biblioteka JSON oparta na C, która jest 2-5x szybsza od standardowego modułu json. Jej API jest niemal identyczne z wbudowanym modułem json, co czyni ją zamiennikiem drop-in. Dobry kompromis między kompatybilnością a szybkością.

Strumieniowanie dużych plików JSONL

Podczas przetwarzania plików JSONL o rozmiarze gigabajtów potrzebujesz podejścia strumieniowego, które czyta, przekształca i zapisuje dane w partiach. Zapewnia to stałe zużycie pamięci i umożliwia śledzenie postępu.

Strumieniowanie dużych plików JSONL
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)

Ten wzorzec używa stałej ilości pamięci, przetwarzając rekordy w partiach o stałym rozmiarze. Parametr batch_size kontroluje kompromis między zużyciem pamięci a wydajnością I/O. W większości systemów partie od 1000 do 10 000 rekordów działają dobrze. Wskaźnik postępu pomaga monitorować długo trwające zadania.

Wypróbuj nasze bezpłatne narzędzia JSONL

Nie chcesz pisać kodu? Użyj naszych bezpłatnych narzędzi online do przeglądania, walidacji i konwersji plików JSONL bezpośrednio w przeglądarce.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL do 1GB bezpośrednio w przeglądarce. Bez przesyłania, 100% prywatności.

Najczęściej zadawane pytania

JSONL w Python — odczyt, zapis, strumieniowanie i walidac...