Pandas · Function

read_json

Reads JSON text, files, URLs, or file-like objects into a pandas Series or DataFrame. It also supports line-delimited and compressed JSON, with chunksize enabling batch iteration.

How it works

Pass JSON text, a path, or a file-like object to read_json. Pandas interprets the input according to orient, optionally parses line-delimited records, and returns a DataFrame or Series; chunksize enables incremental reading through a JsonReader.

Syntax

pandas.read_json(path_or_buf, *, orient=None, typ='frame', dtype=None, convert_axes=None, convert_dates=True, keep_default_dates=True, precise_float=False, date_unit=None, encoding=None, encoding_errors='strict', lines=False, chunksize=None, compression='infer', nrows=None, storage_options=None, dtype_backend=<no_default>, engine='ujson')

Parameters

Name	Type	Description
`path_or_buf`	`str, path object, or file-like object`	JSON string, path-like object, URL, or file-like object containing the input.
`orient`	`str, optional`	Expected JSON representation, such as split, records, index, columns, values, or table.
`typ`	`str, default 'frame'`	Object type to recover: Series or DataFrame.
`dtype`	`bool or dict, optional`	Whether to force or specify column dtypes.
`convert_dates/date_unit`	`bool or list-like; str, optional`	Whether to parse date-like data and which date unit to use.
`lines`	`bool, default False`	Whether each input line is an independent JSON object.
`chunksize`	`int, optional`	Number of rows per returned chunk; enables a JsonReader.
`compression`	`str or dict, default 'infer'`	Compression handling for the input; infer detects it from the path extension.
`nrows`	`int, optional`	Maximum number of rows to read.
`dtype_backend`	`str, default pandas._libs.lib.no_default`	Backend used for nullable dtypes.
`engine`	`str, default 'ujson'`	JSON parsing engine.

Returns

Series, DataFrame, or pandas.api.typing.JsonReader. A JsonReader is returned when chunksize is not 0 or None.

Key points

read_json converts JSON text into a pandas object.
The input can be a JSON file or JSON-like source, not only an in-memory string.
The function handles line-delimited and compressed inputs as well as multiple JSON orientations.
A string path is a supported input form.
Supported URL schemes include HTTP, FTP, S3, and file URLs.
Providing a nonzero chunksize returns a JsonReader for incremental processing.

Common mistakes

Setting chunksize changes the result from an eagerly loaded pandas object to an iterator, so consume it in batches.
A string input may be treated as a URL, so distinguish URL-like sources from local paths when constructing inputs.

Example: Read indexed JSON into a DataFrame

import pandas as pd

payload = '{"alice": {"score": 91}, "bob": {"score": 84}}'
df = pd.read_json(payload, orient="index")
print(df)

Reads an object whose top-level keys become row labels and returns a DataFrame.

When to use it

Import JSON data

Load a JSON API response or local JSON document into a DataFrame for analysis.

Process JSON Lines

Read newline-delimited event records with lines=True and process them in batches.

Load compressed data

Read compressed JSON directly when the source path or compression option identifies its format.

Interview questions

QWhat does pandas.read_json do and what does it return?

read_json accepts a JSON string, path, or file-like input and converts it to a pandas object. By default, typ is frame, so tabular input normally produces a DataFrame.

Follow-up: How would you process a large newline-delimited JSON file? Use lines=True and set chunksize to obtain a JsonReader instead of loading all records at once.

QWhy is the orient parameter important?

orient tells pandas which JSON layout to expect, such as records, index, columns, split, values, or table. The selected layout determines how keys, indexes, and columns are reconstructed.

Follow-up: How would you read an object keyed by row labels? Choose orient="index", optionally supplying columns when the JSON values are record-like.

QHow do lines and chunksize support streaming-style ingestion?

With lines=True, pandas reads line-delimited JSON, where each line represents a separate JSON object. With chunksize set, the function returns a JsonReader for iterative consumption.

Follow-up: What memory behavior should be expected without chunksize? The function loads the result as a Series or DataFrame rather than exposing a batch iterator.

pandas.DataFrame.to_json
pandas.Series.to_json
pandas.read_table
pandas.read_orc

Source: pandas.read_json. Checked 2026-10-15.