PD-01-002-P · Primer — Creating DataFrames from Dictionaries

The idea in one sentence

A Python dictionary where each key maps to a list becomes a DataFrame in which every key turns into a column and every list holds that column's values.

Why it exists

Most of the time your data starts life as something you already know: plain Python. You have a few columns in your head — names, ages, cities — and the most natural way to jot them down is a dictionary of lists, one list per column. pandas meets you exactly there. Instead of forcing you to learn a new data-entry format, the pd.DataFrame(...) constructor accepts that everyday dict directly and hands back a tidy, labeled table you can filter, sort, and analyze. It is the fastest bridge from "I have some data in my code" to "I have a real DataFrame," which is why almost every pandas tutorial, test snippet, and quick experiment begins here.

How it works

You pass a dictionary to the pd.DataFrame() constructor. Each key becomes a column label, and the list attached to that key becomes the values running down that column, top to bottom. Because the columns are built from separate lists, all the lists must be the same length — pandas lines them up row by row. You never specify the rows explicitly, so pandas creates a default row index: the integers 0, 1, 2, .... The result is a two-dimensional table where you can immediately inspect df.columns (the keys) and df.index (the auto-generated row labels).

import pandas as pd

data = {
    "name": ["Ada", "Grace", "Alan"],
    "age": [36, 45, 41],
    "city": ["London", "New York", "London"],
}

df = pd.DataFrame(data)
print(df)
# Expected output:
#     name  age      city
# 0    Ada   36    London
# 1  Grace   45  New York
# 2   Alan   41    London

The one gotcha

Every list in the dictionary must have the same length. If one column has three values and another has two, pandas cannot line the rows up and raises ValueError: All arrays must be of the same length. Count your values before you build — a single missing entry breaks the whole table. (When you genuinely have a gap, put None in that slot instead of leaving it out.)

See it — keys become columns, lists become values

flowchart LR
  A["Python dict<br/>key -> list of values"] --> B["pd.DataFrame(...)<br/>constructor"]
  B --> C["DataFrame table"]
  C --> D["keys become columns<br/>(name, age, city)"]
  C --> E["lists become<br/>column values"]
  C --> F["auto row index<br/>0, 1, 2"]

The one-line takeaway

Hand pd.DataFrame() a dict of equal-length lists, and each key becomes a column while pandas numbers the rows 0, 1, 2, ... for you.

Where you'll meet it

You will use this constant­ly for quick experiments, worked examples, and unit tests where typing a tiny table by hand beats loading a file. It is also how you assemble results you have computed in a loop, and how nearly every pandas lesson (including the rest of this course) spins up sample data to demonstrate the next idea.

Named concepts: dict of lists, columns, row index, constructor