Por Jerry Fan

JSONL en Python: leer, escribir y parsear

Una guía completa para trabajar con archivos JSONL (JSON Lines) en Python. Aprende a leer, escribir, parsear y procesar datos JSONL en streaming con los módulos incluidos en Python, pandas y bibliotecas de alto rendimiento.

¿Por qué usar Python para trabajar con JSONL?

Python es el lenguaje más popular para trabajar con archivos JSONL, y con razón. Incluye el módulo json para parsear JSON sin instalar nada, permite recorrer archivos con un uso eficiente de la memoria y cuenta con bibliotecas potentes como pandas y orjson para tareas más específicas. Tanto si procesas datasets de aprendizaje automático como logs de aplicaciones o respuestas de API, Python te facilita el trabajo con JSONL.

JSONL (JSON Lines) almacena un objeto JSON por línea, por lo que resulta ideal para el procesamiento en streaming, los logs en los que solo se añaden registros y el procesamiento de grandes datasets sin cargarlos por completo en memoria. La lectura de archivos línea a línea en Python encaja perfectamente con este formato. En esta guía aprenderás tres formas de leer JSONL, dos de escribirlo y cómo trabajar con archivos que no caben en memoria.

Leer archivos JSONL en Python

Hay varias formas de leer archivos JSONL en Python, según lo que necesites. El módulo estándar json sirve para la mayoría de los casos, pandas facilita el análisis de datos tabulares y los generadores son la mejor opción para archivos grandes.

La forma más sencilla es usar el módulo json incluido en Python. Abre el archivo, recórrelo línea a línea y parsea cada línea con json.loads(). Este método carga todos los registros en una lista en memoria.

Lectura básica con el módulo 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])

Si tus datos JSONL son tabulares (todos los registros tienen las mismas claves), pandas puede cargarlos directamente en un DataFrame con una sola llamada a una función. Es la forma más rápida de empezar a analizar datos JSONL estructurados.

Lectura 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}')

Para trabajar con archivos que no caben en memoria, usa una función generadora. Así obtienes los registros de uno en uno y mantienes constante el consumo de memoria, independientemente del tamaño del archivo. Este es el patrón recomendado para los pipelines de datos en producción.

Uso de generadores para archivos grandes
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

Escribir archivos JSONL en Python

Escribir archivos JSONL es sencillo: serializa cada registro como una cadena JSON y añade un salto de línea. La regla fundamental es escribir un objeto JSON por línea, sin comas al final ni un array que englobe los objetos.

Usa json.dumps() para serializar cada registro y escríbelo seguido de un salto de línea. Configura ensure_ascii=False para conservar los caracteres Unicode en la salida, como los caracteres chinos, japoneses o los emojis.

Escritura básica con el módulo 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')

Si tus datos ya están en un DataFrame de pandas, usa to_json() con orient='records' y lines=True para exportarlos directamente a JSONL. Es la operación inversa a pd.read_json() con lines=True.

Escritura 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')

Bibliotecas de Python para JSONL

Python ofrece varias bibliotecas para parsear JSON, cada una con un rendimiento distinto. La elección depende del tamaño del archivo y del rendimiento que necesites.

json (biblioteca estándar)

Incluido en Python

El módulo json incluido en Python no requiere instalación y funciona en cualquier entorno. Es suficiente para la mayoría de las tareas con JSONL y admite todos los tipos de datos del estándar JSON. Su rendimiento es adecuado para archivos de hasta unos cientos de MB.

orjson

La más rápida

orjson, escrita en Rust, es la biblioteca de JSON más rápida para Python. El parseo y la serialización son de 2 a 10 veces más rápidos que con el módulo estándar json. Devuelve bytes en lugar de cadenas y admite de forma nativa dataclasses, datetime, numpy y tipos UUID.

ujson

Rápida

ujson (UltraJSON) es una biblioteca de JSON escrita en C, de 2 a 5 veces más rápida que el módulo estándar json. Su API es casi idéntica a la de json, por lo que puedes usarla como sustituto directo. Ofrece un buen equilibrio entre compatibilidad y velocidad.

Procesar archivos JSONL grandes en streaming

Para procesar archivos JSONL de varios gigabytes, necesitas leer, transformar y escribir los datos por lotes en streaming. Así mantienes constante el consumo de memoria y puedes seguir el progreso del procesamiento.

Procesar archivos JSONL grandes en streaming
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)

Este patrón mantiene constante el consumo de memoria al procesar los registros en lotes de tamaño fijo. El parámetro batch_size permite ajustar el equilibrio entre el consumo de memoria y la eficiencia de E/S. En la mayoría de los sistemas funcionan bien los lotes de 1.000 a 10.000 registros. El indicador de progreso permite supervisar las tareas de larga duración.

Trabaja con archivos JSONL online

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin subir archivos a ningún servidor, con un 100% de privacidad.

Preguntas frecuentes

Referencias