JSONL in Python: Lettura, Scrittura e Parsing

Una guida completa per lavorare con file JSONL (JSON Lines) in Python. Impara a leggere, scrivere, analizzare e elaborare in streaming dati JSONL usando moduli integrati, pandas e librerie ad alte prestazioni.

Ultimo aggiornamento: Febbraio 2026

Perché Python per JSONL?

Python è il linguaggio più popolare per lavorare con file JSONL, e per buone ragioni. Il modulo json integrato gestisce il parsing JSON nativamente, l'iterazione sui file è efficiente in termini di memoria per impostazione predefinita, e l'ecosistema offre librerie potenti come pandas e orjson per flussi di lavoro specializzati. Che tu stia elaborando dataset di machine learning, log applicativi o risposte API, Python rende la gestione dei JSONL semplice e diretta.

JSONL (JSON Lines) memorizza un oggetto JSON per riga, rendendolo ideale per lo streaming, il logging in modalità append-only e l'elaborazione di grandi dataset senza caricare tutto in memoria. La lettura riga per riga di Python si allinea perfettamente con questo formato. In questa guida imparerai tre approcci per leggere JSONL, due approcci per scriverlo e come gestire file troppo grandi per entrare in memoria.

Leggere File JSONL in Python

Esistono diversi modi per leggere file JSONL in Python, ognuno adatto a casi d'uso differenti. Il modulo standard json funziona per la maggior parte degli scenari, pandas è comodo per l'analisi tabulare e i generatori sono ideali per file di grandi dimensioni.

L'approccio più semplice utilizza il modulo json integrato di Python. Apri il file, itera riga per riga e analizza ogni riga con json.loads(). Questo carica tutti i record in una lista in memoria.

Lettura Base con il Modulo 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])

Se i tuoi dati JSONL sono tabulari (stesse chiavi in ogni record), pandas può leggerli direttamente in un DataFrame con una singola chiamata di funzione. Questo è il modo più veloce per iniziare ad analizzare dati JSONL strutturati.

Lettura con 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}')

Per file troppo grandi per entrare in memoria, usa una funzione generatore. Questa restituisce un record alla volta, mantenendo l'uso della memoria costante indipendentemente dalla dimensione del file. Questo è il pattern consigliato per pipeline di dati in produzione.

Pattern Generator per File di Grandi Dimensioni
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

Scrivere File JSONL in Python

Scrivere file JSONL è semplice: serializza ogni record come stringa JSON e aggiungi un carattere di nuova riga. La regola chiave è un oggetto JSON per riga, senza virgole finali o array che avvolgono il contenuto.

Usa json.dumps() per serializzare ogni record, poi scrivilo seguito da una nuova riga. Imposta ensure_ascii=False per preservare i caratteri Unicode come cinese, giapponese o emoji nell'output.

Scrittura Base con il Modulo 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')

Se i tuoi dati sono già in un DataFrame pandas, usa to_json() con orient='records' e lines=True per esportarli direttamente come JSONL. Questa è l'operazione inversa di pd.read_json() con lines=True.

Scrittura con 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')

Librerie Python per JSONL

Python offre diverse librerie di parsing JSON con caratteristiche di prestazione differenti. La scelta di quella giusta dipende dalla dimensione del file e dai requisiti di performance.

json (stdlib)

Integrato

Il modulo json integrato di Python non richiede installazione e funziona ovunque. È sufficiente per la maggior parte dei carichi di lavoro JSONL e supporta tutti i tipi JSON standard. Le prestazioni sono adeguate per file fino a qualche centinaio di MB.

orjson

Più veloce

orjson è la libreria JSON più veloce per Python, scritta in Rust. Offre parsing e serializzazione da 2 a 10 volte più veloci rispetto al modulo json standard. Restituisce bytes invece di stringhe e supporta nativamente dataclasses, datetime, numpy e tipi UUID.

ujson

Veloce

ujson (UltraJSON) è una libreria JSON basata su C che è da 2 a 5 volte più veloce del modulo json standard. La sua API è quasi identica al modulo json integrato, rendendola un sostituto diretto. Un buon compromesso tra compatibilità e velocità.

Streaming di File JSONL di Grandi Dimensioni

Quando si elaborano file JSONL di dimensioni nell'ordine dei gigabyte, serve un approccio streaming che legge, trasforma e scrive dati in batch. Questo mantiene l'uso della memoria costante e fornisce il tracciamento dei progressi.

Streaming di File JSONL di Grandi Dimensioni
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)

Questo pattern utilizza memoria costante elaborando i record in batch di dimensione fissa. Il parametro batch_size controlla il compromesso tra uso della memoria ed efficienza I/O. Per la maggior parte dei sistemi, batch da 1.000 a 10.000 record funzionano bene. L'indicatore di progresso aiuta a monitorare i lavori a lunga esecuzione.

Prova i Nostri Strumenti JSONL Gratuiti

Non vuoi scrivere codice? Usa i nostri strumenti online gratuiti per visualizzare, validare e convertire file JSONL direttamente nel tuo browser.

Lavora con File JSONL Online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel tuo browser. Nessun caricamento richiesto, 100% privato.

Domande Frequenti

JSONL in Python — Leggere, Scrivere, Streaming e Validare...