Polars · Function

pl.read_json

Reads a JSON file or readable input into a Polars DataFrame. Optional schema controls let you declare or override column types and limit inference scanning.

How it works

Pass a path, readable stream, or bytes containing a JSON file to obtain a DataFrame. You can provide a complete schema, override selected inferred types, and limit how many rows are inspected when Polars infers the schema.

Syntax

polars.read_json(source: str | Path | IOBase | bytes, *, schema: SchemaDefinition | None = None, schema_overrides: SchemaDefinition | None = None, infer_schema_length: int | None = 100) -> DataFrame

Parameters

Name	Type	Description
`source`	`str \| Path \| IOBase \| bytes`	Path to a file or a file-like object, such as an object with a read() method; bytes are also accepted.
`schema`	`SchemaDefinition \| None`	Optional schema expressed as column names, name-type pairs, or a name-to-type mapping.
`schema_overrides`	`SchemaDefinition \| None`	Optional type specifications or overrides for one or more columns.
`infer_schema_length`	`int \| None = 100`	Maximum number of rows scanned for schema inference; defaults to 100.

Returns

DataFrame

Key points

The function parses a JSON file and produces a Polars DataFrame.
source accepts either a filesystem path or an object exposing read(), such as an open file or BytesIO.
Use schema to declare column names and types through a mapping, names, or name-type pairs.
schema_overrides lets you specify or replace types for selected columns.
infer_schema_length controls how many rows are examined while Polars infers column types.
For duplicate JSON object keys, the first key position remains while the final value is retained.

Common mistakes

Setting infer_schema_length to None scans the complete input for inference and can be slow.
Do not assume a readable stream's position has advanced after the function returns.
Map values must be declared explicitly; Polars will not infer the Map type.

Example: Read JSON into a DataFrame

import io
import polars as pl

json_data = '[{"id": 1, "name": "Ada"}, {"id": 2, "name": "Linus"}]'
df = pl.read_json(io.StringIO(json_data), schema_overrides={"id": pl.Int32})
print(df)

Reads a JSON array from a file-like object into a DataFrame while forcing the id column to Int32.

When to use it

JSON ingestion

Load a regular JSON array from disk or memory into a DataFrame.

Type enforcement

Guarantee selected columns use application-required Polars dtypes.

Schema control

Use a partial or complete schema instead of relying entirely on inference.

Interview questions

QWhat does pl.read_json return, and what input can source accept?

It accepts a path, file-like object, or bytes and returns a DataFrame. The function reads a JSON file rather than newline-delimited JSON.

Follow-up: How would you read newline-delimited JSON instead? Use the separate read_ndjson function, whose documentation identifies it as the reader for newline-delimited JSON.

QHow can the schema be controlled?

schema can describe names and types using a mapping, a list of names, or name-type pairs. A list of names replaces the underlying column names, and its length should match the data dimensions.

Follow-up: What happens when schema_overrides and schema both specify a dtype? schema_overrides takes precedence over dtypes inferred from schema.

QWhat is infer_schema_length used for?

infer_schema_length limits the number of rows inspected for schema inference and defaults to 100. None scans the full data, which can be slow.

Follow-up: When would a complete scan be useful? It can improve inference when later rows contain values needed to determine the intended column types, at the cost of scanning more input.

polars.read_ndjson
polars.DataFrame.write_json
polars.DataFrame.deserialize

Source: polars.read_json — Polars documentation. Checked 2026-10-15.