Introduction

Creating a dictionary from two DataFrame columns is a common way to turn tabular data into a lookup structure. The simplest solution is short, but correctness depends on how you want to handle duplicate keys, missing values, and column types. If you decide those rules up front, the conversion is straightforward and reliable.

Use zip for the Basic Case

When one column should become keys and another should become values, zip is the most direct approach.

1import pandas as pd
2
3df = pd.DataFrame(
4    {
5        "code": ["A", "B", "C"],
6        "value": [10, 20, 30],
7    }
8)
9
10mapping = dict(zip(df["code"], df["value"]))
11print(mapping)

Output:

{'A': 10, 'B': 20, 'C': 30}

This is clear and efficient for normal one-to-one mappings.

Use set_index(...).to_dict() for DataFrame Pipelines

Another idiomatic Pandas pattern is to make one column the index and convert the other to a dictionary.

mapping = df.set_index("code")["value"].to_dict()
print(mapping)

This reads nicely when you are already performing index-oriented operations in a Pandas pipeline.

Duplicate Keys Need an Explicit Policy

Python dictionaries cannot keep multiple values under the same key unless you design them to. If duplicate keys exist, later rows overwrite earlier ones in the normal conversion.

1df = pd.DataFrame(
2    {
3        "code": ["A", "A", "B"],
4        "value": [10, 99, 20],
5    }
6)
7
8mapping = dict(zip(df["code"], df["value"]))
9print(mapping)

Output:

{'A': 99, 'B': 20}

If that is not the intended rule, handle duplicates explicitly.

Keep the first occurrence:

1mapping_first = (
2    df.drop_duplicates(subset=["code"], keep="first")
3      .set_index("code")["value"]
4      .to_dict()
5)

Keep all values per key:

grouped = df.groupby("code")["value"].apply(list).to_dict()
print(grouped)

The important part is not the exact method. It is making the duplicate-key rule explicit rather than accepting accidental overwrite behavior.

Clean Missing Data Before Converting

Missing keys or values can produce awkward lookup results. If the mapping should only contain complete entries, drop incomplete rows first.

1df = pd.DataFrame(
2    {
3        "code": ["A", None, "C"],
4        "value": [10, 20, None],
5    }
6)
7
8clean = df.dropna(subset=["code", "value"])
9mapping = dict(zip(clean["code"], clean["value"]))
10print(mapping)

If missing values are meaningful in your application, keep them intentionally and document the behavior.

Wrap the Conversion in a Helper

If the pattern appears in several places, define a helper so duplicate and missing-value rules stay consistent.

1from typing import Any
2
3
4def frame_to_mapping(frame: pd.DataFrame, key_col: str, value_col: str) -> dict[Any, Any]:
5    required = {key_col, value_col}
6    if not required.issubset(frame.columns):
7        missing = required - set(frame.columns)
8        raise ValueError(f"Missing columns: {sorted(missing)}")
9
10    clean = frame.dropna(subset=[key_col, value_col])
11    return dict(zip(clean[key_col], clean[value_col]))

That is easier to test than repeating slightly different conversion code in notebooks, scripts, and services.

Consider Composite Keys When One Column Is Not Enough

Sometimes the real key is a combination of two columns. A dictionary can still handle that by using tuples as keys.

1df = pd.DataFrame(
2    {
3        "country": ["CA", "CA", "US"],
4        "city": ["Toronto", "Montreal", "Austin"],
5        "population": [3000000, 1800000, 1000000],
6    }
7)
8
9mapping = {
10    (row.country, row.city): row.population
11    for row in df.itertuples(index=False)
12}
13
14print(mapping)

This is often clearer than pretending one column alone is unique when it is not.

Common Pitfalls

The most common pitfall is forgetting that duplicate keys overwrite earlier values in a normal dictionary conversion.

Another issue is converting without checking for missing values, then debugging odd lookup behavior later.

People also sometimes rebuild the same mapping repeatedly inside loops when it could be created once and reused.

Finally, if the mapping crosses a system boundary such as JSON output, remember that some key types are more portable than others.

Summary

• Use dict(zip(df[key], df[value])) for the simplest two-column mapping.
• 'set_index(...).to_dict() is another idiomatic Pandas approach.'
• Decide how duplicate keys should behave before converting.
• Drop or handle missing values intentionally.
• Use tuple keys when the real lookup key spans multiple columns.