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.

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:
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:
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.
| Criterion | ChainMap | Merged dict |
|---|---|---|
| Memory | No copy; references original maps | New dict with all entries |
| Update behavior | Writes go to first map | Must rebuild on change |
| Lookup speed | O(n) in number of maps | Direct hash lookup |
| Best for | Layered config, dynamic scopes | Static 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:
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.