Polars · Class

pl.DataFrame

polars.DataFrame constructs an eager two-dimensional table from common columnar or row-oriented inputs. It can infer the schema or use an explicitly declared schema, with optional control over orientation and inference depth.

How it works

Calling polars.DataFrame creates an eager, two-dimensional table from column-oriented or row-oriented input. Polars can infer column types, or you can provide a schema; when orientation is not specified, it infers the interpretation from the input dimensions and defaults to columns when that is inconclusive.

Syntax

class polars.DataFrame(data=None, schema=None, *, schema_overrides=None, strict=True, orient=None, infer_schema_length=100, nan_to_null=False)

Parameters

Name	Type	Description
`data`	`dict, Sequence, ndarray, Series, or pandas.DataFrame`	Two-dimensional input; accepted forms include dict, sequence, ndarray, Series, or pandas.DataFrame.
`schema`	`Sequence of str, (str, DataType) pairs, or dict[str, DataType]`	Schema supplied as column names, typed name/type pairs, or a name-to-type mapping.
`orient`	`{'col', 'row'} \| None`	Whether two-dimensional data is interpreted by columns or rows; defaults to inferred orientation.
`infer_schema_length`	`int \| None`	Maximum number of rows used for schema inference.

Returns

A polars.DataFrame containing the supplied data with the resulting schema.

Key points

Creates a table from several input families, including mappings, sequences, arrays, Series, and pandas DataFrames.
The schema argument controls the resulting column names and data types.
A schema mapping can leave individual types as None, allowing Polars to infer those types.
infer_schema_length limits how many rows Polars examines when inferring types.
The orient parameter explicitly selects column or row interpretation for two-dimensional input.

Common mistakes

When using two-dimensional input, an omitted orientation is inferred from dimensions, which can produce unexpected interpretation if the dimensions are ambiguous.
A schema can be supplied in multiple forms, so ensure the chosen form matches the input and intended column names and types.

Example: Create a typed DataFrame

import polars as pl

df = pl.DataFrame(
    {"name": ["Ada", "Linus"], "years": [36, 55]},
    schema={"name": pl.String, "years": pl.Int64},
)
print(df)

Constructs a DataFrame from a dictionary and explicitly declares the column types.

When to use it

Create tabular data

Turn dictionaries, sequences, or arrays into an eager table for analysis.

Declare a schema

Enforce names and Polars data types at construction time.

Control orientation

Load nested two-dimensional values whose row/column meaning is known.

Tune schema inference

Limit scanning cost or influence type inference for large inputs.

Interview questions

QWhat is polars.DataFrame used for, and what inputs does its constructor accept?

polars.DataFrame represents two-dimensional data as a table with rows and columns. Its constructor accepts dictionary, sequence, NumPy array, Series, or pandas DataFrame input.

Follow-up: How can construction control types? Supply a schema, such as a mapping from column names to Polars data types; unspecified types may be inferred.

QHow does schema specification work?

The constructor can infer the schema from the input or use an explicitly supplied schema. A dictionary schema maps names to data types, while a list of names declares column names.

Follow-up: What happens when a mapping schema assigns None to a type? That type is auto-inferred from the corresponding data.

QHow does the constructor decide whether nested data is row-oriented or column-oriented?

orient determines whether two-dimensional input is interpreted as columns or rows. If it is omitted, Polars compares column and data dimensions; if that is inconclusive, it uses column orientation.

Follow-up: When should orient="row" be selected? Use it when each inner sequence represents a row and dimension matching does not unambiguously establish that intent.

polars.Series
polars.DataFrame.schema
polars.from_dataframe

Source: DataFrame — Polars documentation. Checked 2026-10-15.