著者: Jerry Fan

Python で JSONL を扱う:読み込み・書き込み・解析

Python で JSONL(JSON Lines)ファイルを扱う方法をまとめたガイドです。組み込みモジュールや pandas、高性能なライブラリを使って、JSONL データの読み込み、書き込み、解析、ストリーミング処理を行う方法を解説します。

JSONL の処理に Python が選ばれる理由

Python は JSONL ファイルの処理に最もよく使われる言語であり、それには理由があります。組み込みの json モジュールですぐに JSON を解析でき、ファイルを順に読み込むだけでメモリを効率よく使えます。また、用途に応じて pandas や orjson などの強力なライブラリも利用できます。機械学習のデータセット、アプリケーションログ、API レスポンスなど、どのようなデータでも、Python なら JSONL を手軽に扱えます。

JSONL(JSON Lines)は、1行に1つの JSON オブジェクトを格納する形式です。ストリーミング処理やログの追記に適しており、大規模なデータセットも全体をメモリに読み込まずに処理できます。Python のファイルを1行ずつ読み込む仕組みは、この形式と相性がよいものです。このガイドでは、JSONL を読み込む3つの方法と書き込む2つの方法に加え、メモリに収まらないファイルの処理方法を紹介します。

Python で JSONL ファイルを読み込む

Python で JSONL ファイルを読み込む方法は複数あり、用途に応じて使い分けられます。たいていの処理には標準の json モジュールで対応できます。表形式のデータを分析するなら pandas が便利で、大容量ファイルにはジェネレーターが適しています。

最もシンプルなのは、Python 組み込みの json モジュールを使う方法です。ファイルを開いて1行ずつ読み込み、各行を json.loads() で解析します。この方法では、すべてのレコードをメモリ上のリストに格納します。

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])

JSONL データが表形式で、すべてのレコードに同じキーがある場合は、pandas の関数を1回呼び出すだけで DataFrame に直接読み込めます。構造化された JSONL データの分析をすぐに始められる方法です。

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

メモリに収まらない大容量ファイルには、ジェネレーター関数を使います。1レコードずつ返すため、ファイルサイズにかかわらずメモリ使用量を一定に保てます。本番環境のデータパイプラインで推奨される方法です。

ジェネレーターで大容量ファイルを読み込む
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

Python で JSONL ファイルを書き込む

JSONL ファイルへの書き込みはシンプルです。各レコードを JSON 文字列にシリアライズし、その後ろに改行文字を付けます。1行に1つの JSON オブジェクトを記述し、末尾にカンマを付けたり、全体を配列で囲んだりしないことが基本ルールです。

json.dumps() で各レコードをシリアライズし、その後ろに改行を付けて書き込みます。ensure_ascii=False を指定すると、中国語や日本語、絵文字などの Unicode 文字をそのまま出力できます。

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

データがすでに pandas の DataFrame に入っている場合は、to_json() に orient='records' と lines=True を指定すると、JSONL として直接出力できます。これは、pd.read_json() に lines=True を指定して読み込む操作の逆にあたります。

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

JSONL を扱う Python ライブラリ

Python には JSON を解析するライブラリが複数あり、それぞれ性能に特徴があります。ファイルサイズや必要な処理速度に応じて選びましょう。

json(標準ライブラリ)

組み込み

Python 組み込みの json モジュールは、追加のインストールなしで、どの環境でも使えます。JSONL を扱うほとんどの処理に対応でき、標準の JSON のデータ型をすべてサポートしています。数百 MB までのファイルであれば、十分な性能を備えています。

orjson

最速

orjson は、Rust で書かれた最速の Python 向け JSON ライブラリです。標準の json モジュールに比べ、解析とシリアライズが2〜10倍高速です。文字列ではなくバイト列を出力し、dataclass、datetime、numpy、UUID 型に標準で対応しています。

ujson

高速

ujson(UltraJSON)は C で実装された JSON ライブラリで、標準の json モジュールより2〜5倍高速です。API が組み込みの json モジュールとほぼ同じなので、そのまま置き換えて使えます。互換性と速度のバランスを取りたい場合に適しています。

大容量 JSONL ファイルをストリーミング処理する

ギガバイト規模の JSONL ファイルを扱うには、データをバッチ単位で読み込み、変換して書き出すストリーミング処理が必要です。この方法なら、メモリ使用量を一定に保ちながら、処理の進捗も確認できます。

大容量 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)

この方法では、一定件数のレコードをバッチにまとめて処理することで、メモリ使用量を一定に保ちます。batch_size パラメータで、メモリ使用量と I/O 効率のバランスを調整できます。多くのシステムでは、バッチあたり1,000〜10,000 レコードが適切です。進捗表示があるため、長時間かかるジョブの処理状況も確認できます。

JSONL ファイルをオンラインで扱う

最大 1GB の JSONL ファイルを、ブラウザ上で直接表示、検証、変換できます。アップロードは不要で、プライバシーは100% 保たれます。

よくある質問

参考資料