pandas DataFrame() — build a table from dicts, lists, arrays, and Series

What it does

pd.DataFrame(data, index, columns, dtype, copy) turns almost any tabular-ish Python object into a DataFrame. The shape of `data` decides the layout: a list of dicts becomes one row per dict (missing keys become NaN), a dict of lists or Series becomes one column per key, a 2D NumPy array needs columns= to get names, and a dict with tuple keys builds MultiIndex columns for free. index and columns override or supply the labels; dtype forces one dtype across everything (ints become floats); copy=False asks pandas to share memory with the input instead of duplicating it.

Why it matters

Everything else in pandas — query, merge, groupby — operates on a DataFrame, so the constructor is the one API you cannot skip. In real work it shows up as: assembling a report from rows pulled off an API (list of dicts), aligning two sensors that logged different hours (dict of Series, which union-aligns the index), giving a NumPy matrix from legacy code real column names, and hard-typing columns before a Parquet write so downstream schemas stay stable. Get the constructor's rules right once and every ingestion path after it behaves predictably.

Example

$ A customer API returns orders as JSON rows. The natural ingestion is a list of dicts — one dict per row, keys become columns:

   order_id    city  revenue
0      1001  Berlin    144.0
1      1002  Vienna     55.3
2      1003  Berlin    384.0
order_id      int64
city            str
revenue     float64
dtype: object

$ Two machine sensors logged different hours; you want one aligned table anyway. A dict of Series union-aligns the index and fills the gaps:

        price  units
berlin  810.0   12.0
vienna  640.0    NaN
zurich    NaN    9.0

$ Legacy code hands you a bare NumPy matrix plus you need forced column names — or you want a column order you choose yourself:

    x  y  z
r1  1  2  3
r2  4  5  6

Common flags

data

ndarray, dict of arrays/Series, list of dicts, list of lists, another DataFrame — the input shape sets the layout

index=...

row labels; supply with ndarray/list data, or conform/override existing index

columns=...

column names; required (or at least useful) for bare arrays, reorderable for dict input

dtype='float64'

force one dtype everywhere; int columns upcast, strings stay strings

copy=False

share input data instead of copying — safe under pandas 3.0's Copy-on-Write, but writes to either object then trigger a copy

list of Series

pd.DataFrame([s1, s2]) treats each Series as a ROW; the dict form {'a': s1} treats each Series as a column — the most common constructor mix-up

scalar broadcast

pd.DataFrame({'city': ['Berlin', 'Vienna'], 'country': 'DE'}) — a scalar fills the whole column