Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python ChainMap: Combining Dictionaries with a Single Lookup

Learn how Python's ChainMap combines multiple dictionaries into one view, preserving lookup order and keeping configuration layers separate.

~4 min readPython
#ChainMap#Python dictionaries#collections module#lookup order
Illustration of Python ChainMap combining three dictionaries into a single lookup view with priority order.

When you need to look up a key across several dictionaries in a defined priority order, copying and merging them is often wasteful. Python's ChainMap, from the collections module, provides a view over multiple mappings without copying data, so lookups follow the order of the maps you supply. This is especially useful for layered configuration, environment overrides, and namespace scoping.

Why Use a ChainMap Instead of Merging?

Consider a typical configuration setup: you have a set of defaults, a user-specific overrides file, and environment variables. The precedence is usually environment first, then user settings, then defaults. If you merge them into a single dictionary, you lose the original source boundaries and must rebuild the merged object every time any layer changes. With ChainMap, you keep each mapping separate and simply stack them. A lookup walks through the maps in order and returns the first value found, which naturally implements the precedence you want.

Creating a ChainMap

You create a ChainMap by passing the mappings you want to search, with the first mapping having the highest priority:

python
from collections import ChainMap defaults = {'theme': 'light', 'language': 'en'} user = {'theme': 'dark'} combined = ChainMap(user, defaults) print(combined['theme']) # 'dark' print(combined['language']) # 'en'

The ChainMap instance itself is a mapping, so it supports the usual methods like .get(), .keys(), and .items(). However, iteration and len() only consider the first mapping in the chain, which is a common point of confusion.

How Lookup Order Works

Lookup order is determined by the sequence of maps passed to the constructor. When you access combined[key], Python checks the first map, then the second, and so on until the key is found. If no map contains the key, a KeyError is raised. This behavior is exactly what you need for override logic. It also means that key in combined returns True if the key exists in any map, but combined.keys() only shows keys from the first map. If you need all unique keys across the chain, you can use set().union(*combined.maps).

Updating and Mutating Mappings

The ChainMap object is a view, not a merged copy. When you assign to combined[key] = value, the update is applied to the first map only. This is intentional: it lets you write configuration overrides without touching the underlying defaults. For example:

python
combined['language'] = 'fr' print(user['language']) # 'fr' print(defaults['language']) # still 'en'

If you want to add a new mapping to the chain, use combined.new_child(new_map) to return a new ChainMap with new_map prepended, or mutate combined.maps directly with combined.maps.insert(0, new_map) or combined.maps.append(new_map) to add it at the end. The maps attribute is a list of the underlying mappings, so you can reorder, insert, or remove mappings as needed. This mutability is powerful but requires care: if you modify a mapping that is already part of a ChainMap, the change is immediately visible through the chain.

Choosing Between ChainMap and a Merged Dictionary

A merged dictionary is simpler when you need a snapshot of the combined data and the underlying sources rarely change. Use {**defaults, **user} or defaults | user (Python 3.9+) to create a new dict. This is fine for a one-time lookup or when you need to pass a plain dict to a function that doesn't expect a ChainMap. However, merging copies all key-value pairs, which costs memory and time. If the layers are large or updated frequently, ChainMap avoids that overhead and keeps the source separation.

CriterionChainMapMerged dict
MemoryNo copy; references original mapsNew dict with all entries
Update behaviorWrites go to first mapMust rebuild on change
Lookup speedO(n) in number of mapsDirect hash lookup
Best forLayered config, dynamic scopesStatic snapshots, simple overrides

Performance and Memory Considerations

In the worst case, a ChainMap lookup is O(n) in the number of maps in the chain, because each miss requires checking the next map. In practice, with a small number of layers (e.g., 2–5), the overhead is negligible. But if you have dozens of maps and frequent lookups, a merged dictionary may be faster. Memory-wise, ChainMap stores no duplicate data; it holds references to the original mappings. This is a clear win when the underlying dictionaries are large and you want to avoid copying. The tradeoff is that the chain is not a snapshot—changes to any underlying map affect the chain immediately, which can be surprising if you expected a frozen view.

Practical Example: Layered Configuration

A common pattern is to combine environment variables, a user config file, and defaults into a single lookup. Here is a minimal example:

python
import os from collections import ChainMap def load_config(): defaults = {'host': 'localhost', 'port': 8080, 'debug': False} user_config = {'port': 9090} # normally read from a file env = {'debug': os.getenv('DEBUG', 'false').lower() == 'true'} return ChainMap(env, user_config, defaults) config = load_config() print(config['host']) # 'localhost' print(config['port']) # 9090 print(config['debug']) # True if DEBUG is 'true' (case-insensitive)

The lookup order ensures environment variables override user settings, which override defaults. If you later need to add a command-line override, you can create a new chain with config.new_child(cli_args) or insert the override at the front of the existing chain with config.maps.insert(0, cli_args). This keeps the configuration logic explicit and avoids merging multiple sources into a single dict that would need to be updated every time a layer changes.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.