How to Convert a pandas DataFrame to a Dictionary Using DataFrame.to_dict()

Use DataFrame.to_dict() to convert pandas DataFrames into Python dictionaries, with the orient parameter controlling whether the output maps columns to values, rows to records, or index labels to row dictionaries.

The pandas library provides a built-in method for serializing tabular data into native Python dictionaries. In the pandas-dev/pandas repository, the DataFrame.to_dict() method implemented in pandas/core/frame.py offers flexible conversion patterns through multiple orientation options and support for custom dictionary subclasses.

Understanding the DataFrame.to_dict() Method Signature

The to_dict() method signature in pandas/core/frame.py defines two key parameters that control the conversion behavior:

DataFrame.to_dict(self, orient: str = "dict", into: type[dict] = dict) -> dict

The orient parameter accepts string values that determine the structure of the resulting dictionary, while into allows specification of alternative dictionary-like classes such as OrderedDict. According to the source code, the implementation delegates to helper functions in pandas/core/methods/to_dict.py, which are shared with Series.to_dict in pandas/core/series.py to ensure consistent behavior across data structures.

Orient Options for pandas DataFrame to dict Conversion

The orient parameter supports five distinct layouts for the output dictionary.

Default "dict" Orientation (Column-Oriented)

The default "dict" orientation maps each column name to a nested dictionary of index-value pairs:

import pandas as pd

df = pd.DataFrame({
    "A": [1, 2, 3],
    "B": ["x", "y", "z"]
}, index=["i1", "i2", "i3"])

default_dict = df.to_dict()

# {'A': {'i1': 1, 'i2': 2, 'i3': 3},

#  'B': {'i1': 'x', 'i2': 'y', 'i3': 'z'}}

This is the standard behavior when calling to_dict() without arguments.

"list" Orientation (Column to List)

The "list" orientation maps each column name to a list of values, preserving order but dropping index labels:

list_dict = df.to_dict(orient="list")

# {'A': [1, 2, 3], 'B': ['x', 'y', 'z']}

"records" Orientation (Row-Wise List)

The "records" orientation returns a list of dictionaries, where each dictionary represents one row with column names as keys:

records_dict = df.to_dict(orient="records")

# [{'A': 1, 'B': 'x'},

#  {'A': 2, 'B': 'y'},

#  {'A': 3, 'B': 'z'}]

This format is commonly used for JSON serialization.

"index" Orientation (Index-Oriented)

The "index" orientation inverts the default structure, mapping each index value to a dictionary of column-value pairs:

index_dict = df.to_dict(orient="index")

# {'i1': {'A': 1, 'B': 'x'},

#  'i2': {'A': 2, 'B': 'y'},

#  'i3': {'A': 3, 'B': 'z'}}

"series" Orientation

The "series" orientation maps column names to pandas.Series objects rather than plain Python dictionaries or lists:

series_dict = df.to_dict(orient="series")

# {'A': Series([1, 2, 3], index=['i1', 'i2', 'i3']),

#  'B': Series(['x', 'y', 'z'], index=['i1', 'i2', 'i3'])}

Using Custom Dictionary Types with the into Parameter

The into parameter enables use of ordered dictionaries or other mapping types from the standard library. By importing OrderedDict and passing it to into, the resulting dictionary maintains insertion order:

from collections import OrderedDict

ordered_dict = df.to_dict(into=OrderedDict)

The implementation in pandas/core/methods/to_dict.py handles the instantiation of the specified class while maintaining the selected orientation structure.

Complete Code Examples

Here is a comprehensive example demonstrating the pandas DataFrame to dict conversion patterns:

import pandas as pd
from collections import OrderedDict

# Create sample DataFrame

df = pd.DataFrame({
    "A": [1, 2, 3],
    "B": ["x", "y", "z"]
}, index=["i1", "i2", "i3"])

# Default orientation: column -> {index: value}

result_default = df.to_dict()

# List orientation: column -> [values]

result_list = df.to_dict(orient="list")

# Records orientation: list of row dictionaries

result_records = df.to_dict(orient="records")

# Index orientation: index -> {column: value}

result_index = df.to_dict(orient="index")

# Using OrderedDict

result_ordered = df.to_dict(into=OrderedDict)

Summary

• DataFrame.to_dict() in pandas/core/frame.py provides the primary interface for converting pandas DataFrame to dict objects.
• The orient parameter accepts "dict", "list", "series", "records", and "index" to control output structure.
• The into parameter supports custom dictionary subclasses like OrderedDict.
• Helper functions in pandas/core/methods/to_dict.py ensure consistent behavior between DataFrame and Series conversions.

Frequently Asked Questions

What is the default orientation when converting a pandas DataFrame to dict?

The default orient value is "dict", which returns a dictionary mapping each column name to a nested dictionary of index-value pairs. This structure preserves both column and index information in a hierarchical format.

How do I convert a DataFrame to a list of dictionaries?

Pass orient="records" to DataFrame.to_dict(). This returns a list where each element is a dictionary representing a single row, with keys corresponding to column names and values containing the row data. This format matches standard JSON record structure.

Can I use OrderedDict when converting a pandas DataFrame to dict?

Yes. Import OrderedDict from the collections module and pass it to the into parameter: df.to_dict(into=OrderedDict). This ensures the resulting dictionaries maintain insertion order, which is particularly useful for Python versions prior to 3.7 or when order-critical operations depend on the dictionary structure.

Where is the to_dict method implemented in the pandas source code?

The DataFrame.to_dict() method is implemented in pandas/core/frame.py, with shared conversion logic residing in pandas/core/methods/to_dict.py. The Series.to_dict() method in pandas/core/series.py utilizes the same helper functions to ensure consistent dictionary conversion behavior across pandas data structures.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}