Pandas · Module

df.to_json

Serializes a DataFrame to JSON text or writes it to a specified destination. Orientation, date encoding, precision, index handling, line output, compression, and formatting are configurable.

How it works

Call DataFrame.to_json to serialize a DataFrame either to a JSON string or to a destination supplied by path_or_buf. Choose an orient to control the JSON shape; optionally configure date encoding, numeric precision, Unicode handling, line-delimited output, compression, indentation, index inclusion, storage, and write mode.

Syntax

DataFrame.to_json(path_or_buf=None, *, orient=None, date_format=None, double_precision=10, force_ascii=True, date_unit='ms', default_handler=None, lines=False, compression='infer', index=None, indent=None, storage_options=None, mode='w')

Parameters

Name	Type	Description
`path_or_buf`	`str, path object, file-like object, or None`	Destination for the JSON output; if omitted, the method returns a string.
`orient`	`str or None`	JSON structure to produce. DataFrame values include `split`, `records`, `index`, `columns`, `values`, and `table`.
`date_format`	`{None, 'epoch', 'iso'}`	Date encoding, either epoch or ISO 8601.
`double_precision`	`int`	Decimal places for floating-point values; maximum 15.
`force_ascii`	`bool`	Whether to force encoded strings to ASCII.
`date_unit`	`str`	Time unit governing timestamp and ISO 8601 precision.
`default_handler`	`callable or None`	Callable used to serialize otherwise unsupported data types.
`lines`	`bool`	Whether to emit one JSON object per line.
`compression`	`str or dict, default 'infer'`	Compression setting for output.
`index`	`bool or None`	Whether to include the index.
`indent`	`int or None`	Indentation level for pretty-printed JSON.
`storage_options`	`dict or None`	Extra options for filesystem backends.

Returns

str or None. Returns the JSON string when path_or_buf is not provided; otherwise writes to the destination.

Key points

The method serializes the DataFrame and returns JSON text when no output destination is supplied.
DataFrame orientations include split, records, index, columns, values, and table; the default is columns.
Date output can use epoch milliseconds or ISO 8601 representation.
double_precision sets the number of decimal places used for floating-point encoding.
force_ascii=True escapes non-ASCII characters; disable it to preserve Unicode characters.
orient describes the expected structure of the serialized JSON.

Common mistakes

Setting index=False is supported only with split or table orientation.
double_precision cannot exceed 15; larger values raise a ValueError.
Missing values become JSON null, while datetimes use timestamp-style conversion unless configured otherwise.

Example: Serialize rows as JSON records

import pandas as pd

frame = pd.DataFrame({"name": ["Ada", "Linus"], "score": [10, 9]})
json_text = frame.to_json(orient="records")
print(json_text)

Serializes each row as a JSON object and returns the resulting JSON text.

When to use it

Export records for APIs

A row-oriented API payload is needed.

Create JSON Lines output

A compact stream format is required.

Write compressed or remote JSON

Serialized data must be persisted.

Pretty-print JSON

Human-readable serialized output is useful for inspection.

Interview questions

QWhat does orient control?

orient determines the JSON layout. For a DataFrame, supported values include split, records, index, columns, values, and table, with columns as the default.

Follow-up: Which orientation is convenient for row-wise consumers? records, because it represents rows as JSON objects.

QHow are dates encoded?

date_format selects either epoch timestamps or ISO 8601 strings. Its default is ISO for table orientation and epoch for other orientations.

Follow-up: How can timestamp precision be controlled? Use date_unit, whose default is milliseconds.

QHow can output be written as JSON Lines?

With no destination, the method returns a JSON string. Supplying path_or_buf writes the serialized output to that destination; lines=True produces line-delimited JSON and is supported only with records orientation.

Follow-up: What additional setting is needed for append-style line output? Use an appropriate write mode, such as append mode, when writing to a file-like destination.

pandas.DataFrame.to_dict
pandas.DataFrame.to_string
pandas.read_json

Source: pandas.DataFrame.to_json. Checked 2026-10-15.