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 transmitir datos JSONL usando módulos integrados, pandas y bibliotecas de alto rendimiento.

Última actualización: febrero de 2026

¿Por qué Python para JSONL?

Python es el lenguaje más popular para trabajar con archivos JSONL, y con razón. Su módulo json integrado maneja el parseo de JSON de forma nativa, la iteración de archivos es eficiente en memoria por defecto, y el ecosistema ofrece bibliotecas potentes como pandas y orjson para flujos de trabajo especializados. Ya sea que estés procesando datasets de aprendizaje automático, logs de aplicaciones o respuestas de API, Python hace que el manejo de JSONL sea directo.

JSONL (JSON Lines) almacena un objeto JSON por línea, lo que lo hace ideal para streaming, registro de solo adición y procesamiento de grandes datasets sin cargar todo en memoria. La lectura línea por línea de archivos en Python se alinea perfectamente con este formato. En esta guía, aprenderás tres enfoques para leer JSONL, dos enfoques para escribirlo y cómo manejar archivos demasiado grandes para caber en memoria.

Leer archivos JSONL en Python

Hay varias formas de leer archivos JSONL en Python, cada una adecuada para diferentes casos de uso. El módulo json estándar funciona para la mayoría de los escenarios, pandas es conveniente para análisis tabular y los generadores son mejores para archivos grandes.

El enfoque más simple usa el módulo json integrado de Python. Abre el archivo, itera línea por línea y parsea cada línea con json.loads(). Esto 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 (las mismas claves en cada registro), pandas puede leerlos directamente en un DataFrame con una sola llamada de función. Esta 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 archivos demasiado grandes para caber en memoria, usa una función generadora. Esto produce un registro a la vez, manteniendo el uso de memoria constante independientemente del tamaño del archivo. Este es el patrón recomendado para pipelines de datos en producción.

Patrón generador 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 agrega un carácter de nueva línea. La regla clave es un objeto JSON por línea, sin comas finales ni arreglo envolvente.

Usa json.dumps() para serializar cada registro, luego escríbelo seguido de una nueva línea. Establece ensure_ascii=False para preservar caracteres Unicode como chino, japonés o emoji en la salida.

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 como JSONL. Esto es la operación inversa de 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 Python para JSONL

Python ofrece varias bibliotecas de parseo JSON con diferentes características de rendimiento. Elegir la correcta depende del tamaño de tu archivo y los requisitos de rendimiento.

json (stdlib)

Integrado

El módulo json integrado de Python no requiere instalación y funciona en todas partes. Es suficiente para la mayoría de las cargas de trabajo JSONL y soporta todos los tipos JSON estándar. El rendimiento es adecuado para archivos de hasta unos cientos de MB.

orjson

La más rápida

orjson es la biblioteca JSON más rápida de Python, escrita en Rust. Proporciona un parseo y serialización de 2 a 10 veces más rápido en comparación con el módulo json estándar. Produce bytes en lugar de cadenas y soporta nativamente dataclasses, datetime, numpy y tipos UUID.

ujson

Rápida

ujson (UltraJSON) es una biblioteca JSON basada en C que es de 2 a 5 veces más rápida que el módulo json estándar. Su API es casi idéntica al módulo json integrado, lo que la convierte en un reemplazo directo. Un buen punto medio entre compatibilidad y velocidad.

Streaming de archivos JSONL grandes

Al procesar archivos JSONL de gigabytes de tamaño, necesitas un enfoque de streaming que lea, transforme y escriba datos en lotes. Esto mantiene el uso de memoria constante y proporciona seguimiento del progreso.

Streaming de archivos JSONL grandes
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 usa memoria constante procesando registros en lotes de tamaño fijo. El parámetro batch_size controla el equilibrio entre uso de memoria y eficiencia de E/S. Para la mayoría de los sistemas, lotes de 1.000 a 10.000 registros funcionan bien. El indicador de progreso ayuda a monitorear trabajos de larga duración.

Prueba nuestras herramientas JSONL gratuitas

¿No quieres escribir código? Usa nuestras herramientas online gratuitas para ver, validar y convertir archivos JSONL directamente en tu navegador.

large JSONL files guide
JSONL validator
JSONL best practices

Trabaja con archivos JSONL online

Visualiza, valida y convierte archivos JSONL de hasta 1GB directamente en tu navegador. Sin subidas, 100% privado.

Preguntas frecuentes

JSONL en Python — Leer, escribir, transmitir y validar JS...