JSONL em Python: Ler, Escrever e Parsear

Um guia completo para trabalhar com arquivos JSONL (JSON Lines) em Python. Aprenda a ler, escrever, parsear e transmitir dados JSONL usando módulos integrados, pandas e bibliotecas de alto desempenho.

Última atualização: fevereiro de 2026

Por que Python para JSONL?

Python é a linguagem mais popular para trabalhar com arquivos JSONL, e com razão. Seu módulo json integrado lida com o parseamento JSON nativamente, a iteração de arquivos é eficiente em memória por padrão, e o ecossistema oferece bibliotecas poderosas como pandas e orjson para workflows especializados. Seja processando datasets de aprendizado de máquina, logs de aplicação ou respostas de API, Python torna o manuseio de JSONL simples.

JSONL (JSON Lines) armazena um objeto JSON por linha, tornando-o ideal para streaming, logging de append-only e processamento de grandes datasets sem carregar tudo na memória. A leitura linha por linha de arquivos do Python se alinha perfeitamente com este formato. Neste guia, você aprenderá três abordagens para ler JSONL, duas abordagens para escrevê-lo, e como lidar com arquivos grandes demais para caber na memória.

Lendo Arquivos JSONL em Python

Existem várias maneiras de ler arquivos JSONL em Python, cada uma adequada para diferentes casos de uso. O módulo json padrão funciona para a maioria dos cenários, pandas é conveniente para análise tabular, e generators são melhores para arquivos grandes.

A abordagem mais simples usa o módulo json integrado do Python. Abra o arquivo, itere linha por linha e parseia cada linha com json.loads(). Isso carrega todos os registros em uma lista na memória.

Leitura Básica com o 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])

Se seus dados JSONL são tabulares (mesmas chaves em cada registro), pandas pode lê-los diretamente em um DataFrame com uma única chamada de função. Esta é a maneira mais rápida de começar a analisar dados JSONL estruturados.

Leitura com 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 arquivos grandes demais para caber na memória, use uma função generator. Isso retorna um registro por vez, mantendo o uso de memória constante independentemente do tamanho do arquivo. Este é o padrão recomendado para pipelines de dados em produção.

Padrão Generator para Arquivos 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

Escrevendo Arquivos JSONL em Python

Escrever arquivos JSONL é direto: serialize cada registro como uma string JSON e adicione um caractere de nova linha. A regra principal é um objeto JSON por linha, sem vírgulas finais ou array envolvente.

Use json.dumps() para serializar cada registro, depois escreva seguido de uma nova linha. Defina ensure_ascii=False para preservar caracteres Unicode como chinês, japonês ou emoji na saída.

Escrita Básica com o 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')

Se seus dados já estão em um DataFrame do pandas, use to_json() com orient='records' e lines=True para exportá-lo diretamente como JSONL. Esta é a operação inversa de pd.read_json() com lines=True.

Escrita com 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 oferece várias bibliotecas de parseamento JSON com diferentes características de desempenho. Escolher a correta depende do tamanho do seu arquivo e dos requisitos de desempenho.

json (stdlib)

Integrado

O módulo json integrado do Python não requer instalação e funciona em qualquer lugar. É suficiente para a maioria dos workloads JSONL e suporta todos os tipos JSON padrão. O desempenho é adequado para arquivos de até algumas centenas de MB.

orjson

Mais rápido

orjson é a biblioteca JSON mais rápida para Python, escrita em Rust. Oferece parseamento e serialização 2-10x mais rápidos em comparação com o módulo json padrão. Retorna bytes em vez de strings e suporta nativamente dataclasses, datetime, numpy e tipos UUID.

ujson

Rápido

ujson (UltraJSON) é uma biblioteca JSON baseada em C que é 2-5x mais rápida que o módulo json padrão. Sua API é quase idêntica ao módulo json integrado, tornando-a uma substituição direta. Um bom meio-termo entre compatibilidade e velocidade.

Streaming de Arquivos JSONL Grandes

Ao processar arquivos JSONL com gigabytes de tamanho, você precisa de uma abordagem de streaming que lê, transforma e escreve dados em lotes. Isso mantém o uso de memória constante e fornece acompanhamento de progresso.

Streaming de Arquivos 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 padrão usa memória constante processando registros em lotes de tamanho fixo. O parâmetro batch_size controla o equilíbrio entre uso de memória e eficiência de I/O. Para a maioria dos sistemas, lotes de 1.000 a 10.000 registros funcionam bem. O indicador de progresso ajuda a monitorar tarefas de longa duração.

Experimente Nossas Ferramentas JSONL Gratuitas

Não quer escrever código? Use nossas ferramentas online gratuitas para visualizar, validar e converter arquivos JSONL diretamente no seu navegador.

large JSONL files guide
JSONL validator
JSONL best practices

Trabalhe com Arquivos JSONL Online

Visualize, valide e converta arquivos JSONL de até 1GB diretamente no seu navegador. Sem uploads necessários, 100% privado.

Perguntas Frequentes

JSONL em Python — Ler, Escrever, Streaming e Validar JSON...