How to Select Dictionary Keys Recursively in Python
Learn to filter selected keys at every level of a nested Python dictionary, with explicit policies for parent branches, mappings, lists, mutation, and cycles.

To select keys recursively in Python, walk each dictionary’s key-value pairs, keep values whose keys match your selection rule, and recurse into dictionary values. First decide what happens to nonmatching parent keys whose descendants match, whether matching values are also searched, and whether empty branches remain. The implementation below builds a new dictionary, filters every nested dictionary, and keeps ancestor branches when they contain a selected key.
def select_keys(data, wanted):
"""Keep wanted keys at every dict level; retain ancestors of matches."""
wanted = set(wanted)
result = {}
for key, value in data.items():
if isinstance(value, dict):
value = select_keys(value, wanted)
if key in wanted:
result[key] = value
elif isinstance(value, dict) and value:
result[key] = value
return result
source = {
"id": 17,
"profile": {
"name": "Mina",
"email": "mina@example.com",
"preferences": {"theme": "dark", "alerts": True},
},
"audit": {"created": "2025-01-01"},
}
print(select_keys(source, {"name", "theme"}))
# {'profile': {'name': 'Mina', 'preferences': {'theme': 'dark'}}}
The selected keys are name and theme. Their nonmatching ancestors, profile and preferences, are preserved so the selected values remain reachable. Unrelated branches disappear. A matching key’s value is recursively filtered too, so selecting a key does not exempt its nested dictionary from the rule.
1. Define the selection contract
Before adopting a recursive filter, pin down its input and output rules. Python dictionary values can be arbitrary objects, so recursion is not automatic: a utility has to choose which value types it visits. Python’s documentation describes a mapping as associating hashable keys with arbitrary objects. Python built-in types

| Question | Choice in the main example | Alternative |
|---|---|---|
| Which keys match? | Exact membership in a set | A predicate, such as a case-insensitive string check |
| Which values are traversed? | Built-in dictionaries and subclasses | All mapping implementations, or dictionaries inside sequences too |
| What happens to a parent key? | Keep it if its filtered dictionary has descendants selected | Keep only keys that match directly |
| Are empty branches retained? | No, unless the branch key itself matches | Keep all original parents, even when filtering empties them |
| Does the function mutate? | No; it constructs a new dictionary structure | Update the original in place |
These are application policies, not a single prescribed Python algorithm. State them wherever the function is reused. For example, “select” may mean returning only directly matching keys, while “prune” often implies retaining the path to a descendant. The code here uses the latter behavior.
2. Keep directly matching keys only
If parent names should not be retained unless they are themselves selected, use a simpler rule. It recursively inspects values under nonmatching keys, but preserves a matching value as-is:
def select_direct_keys(data, wanted):
wanted = set(wanted)
result = {}
for key, value in data.items():
if key in wanted:
result[key] = value
elif isinstance(value, dict):
nested = select_direct_keys(value, wanted)
if nested:
# Keeping this line retains ancestors of a match.
result[key] = nested
return result
As written, this still retains ancestors when a nested match exists. To keep only direct key matches and discard every nonmatching parent, remove the recursive elif branch. That change means a selected key below a nonselected parent becomes unreachable and is omitted. The function name and documentation should reflect that deliberate policy.
There is another subtle choice: select_direct_keys does not inspect inside a value when its key already matches. If a matching key contains a dictionary, that entire dictionary passes through unchanged. The main implementation avoids this surprise by filtering the value before deciding whether to keep it.
3. Use a key predicate instead of a set
When the selection rule is more expressive than exact membership, accept a callable. This version selects keys that start with public_ and retains the ancestors of selected values:
def select_where(data, predicate):
result = {}
for key, value in data.items():
if isinstance(value, dict):
value = select_where(value, predicate)
if predicate(key):
result[key] = value
elif isinstance(value, dict) and value:
result[key] = value
return result
record = {
"public_id": 4,
"account": {"public_name": "Mina", "private_token": "secret"},
}
filtered = select_where(record, lambda key: isinstance(key, str) and key.startswith("public_"))
# {'public_id': 4, 'account': {'public_name': 'Mina'}}
A predicate makes the key rule flexible: it can use a set, a pattern, a type check, or a combination. Decide how non-string keys behave. The example ignores them because its predicate checks for str; an unguarded key.startswith(...) would raise AttributeError if it receives an integer key. Dictionary keys can be values of different hashable types, so string-only assumptions should be explicit. Python mapping documentation
4. Support any Mapping implementation
Use collections.abc.Mapping if inputs may be read-only proxies or custom mapping classes, not just dictionaries. The abstract base class represents the mapping interface, including item access and iteration. collections.abc documentation
from collections.abc import Mapping
def select_mapping(data, wanted):
"""Return ordinary dicts, accepting any Mapping as input."""
wanted = set(wanted)
result = {}
for key, value in data.items():
if isinstance(value, Mapping):
value = select_mapping(value, wanted)
if key in wanted:
result[key] = value
elif isinstance(value, Mapping) and value:
result[key] = value
return result
This intentionally returns built-in dictionaries at every mapping level. Accepting a custom mapping as input does not imply its type can be recreated safely: constructors differ, some mappings are immutable, and some need extra arguments. If preserving output types matters, define a factory or conversion policy for each supported mapping. The Mapping interface and its mixin methods are documented by Python, but output construction remains the application’s decision. collections.abc.Mapping
For a simple dict-only helper, isinstance(value, dict) is appropriate and includes subclasses. It is usually more flexible than type(value) is dict, which excludes subclasses. Python isinstance documentation
5. Decide how lists and tuples behave
The main implementation descends into dictionary values only. It treats a list or tuple as an ordinary value and returns it unchanged, even if dictionaries appear inside it. That is often the right rule for JSON-like data when the requirement says dictionary keys at every level but does not say to traverse arrays.

If nested dictionaries inside lists should be filtered too, write that traversal explicitly and preserve the sequence type you support:
def select_nested_containers(value, wanted):
if isinstance(value, dict):
result = {}
for key, child in value.items():
filtered = select_nested_containers(child, wanted)
if key in wanted:
result[key] = filtered
elif isinstance(filtered, dict) and filtered:
result[key] = filtered
elif isinstance(filtered, list) and filtered:
result[key] = filtered
return result
if isinstance(value, list):
return [select_nested_containers(item, wanted) for item in value]
if isinstance(value, tuple):
return tuple(select_nested_containers(item, wanted) for item in value)
return value
This version preserves list and tuple containers, but it drops empty filtered mapping/list branches when their parent key does not match. It does not recursively inspect sets, generators, or arbitrary iterables. Avoid treating every iterable as a container by default: strings and bytes are iterable too, and recursive traversal would be inappropriate. Also consider whether a sequence item that becomes an empty dictionary should be omitted or retained; the sample retains it in the list.
6. Mutation, copying, and aliasing
The examples allocate a new dictionary at each traversed dictionary node. They do not mutate the input dictionaries. This makes the source usable after filtering and avoids surprising changes to a caller’s data.
The result is not necessarily a deep copy of every value. Values that are not traversed, such as custom objects, lists in the main implementation, or selected scalar values, are reused by reference. If those objects are mutable, changing one through the result may also affect the source. If isolation is required, define a deeper copying policy; blindly calling copy.deepcopy can be unsuitable for objects with custom copy behavior or external resources.
A mutating version can delete unwanted keys while iterating over a snapshot of the keys, but nested values and parent pruning still need explicit rules. In-place filtering also affects every other reference to the same dictionary. Prefer a new-result function unless callers specifically need mutation and understand the aliasing consequences.
7. Empty branches and exact output shape
In the main recipe, an unmatched parent is included only when its filtered dictionary is nonempty. A directly selected key is retained even if its value is an empty dictionary, list, None, or another false value. This is why the code checks isinstance(value, dict) and value for ancestor retention instead of using a broad truth test on every value.
If empty paths should remain, remove the truth check:
elif isinstance(value, dict):
result[key] = value
If every original parent must remain regardless of matches, copy the parent branches before filtering or implement a separate “preserve shape” policy. Test representative empty cases: an empty input, a selected key whose value is {}, and an unmatched branch whose children all disappear.
8. Complexity, cycles, and reliability
For an acyclic tree of dictionaries, the traversal takes time proportional to the number of visited key-value pairs. It allocates a new dictionary for each visited dictionary, plus space for retained entries; recursive call depth grows with the deepest nested dictionary. Extremely deep input can exceed Python’s recursion limit. If arbitrary depth is possible, use an explicit stack rather than recursive calls.
Ordinary decoded JSON data is tree-shaped, but Python objects can contain cycles or shared references. A cycle such as d["self"] = d makes the recursive implementations call themselves indefinitely until Python raises RecursionError. For untrusted or general object graphs, track identities currently on the recursion path and reject cycles, or define a cycle-preserving output strategy. A global visited set alone can incorrectly collapse shared but acyclic references, so distinguish “currently visiting” objects from objects already completed if shared structure matters.
For dependable behavior, keep these checks in mind:
- Normalize a reusable selection iterable once with
set(wanted); otherwise a generator may be exhausted after the first level. - Ensure wanted keys are hashable because set membership requires hashing.
- Use a predicate if key comparison cannot be represented by set membership.
- Specify treatment of sequences, empty containers, custom mappings, and cycles.
- Use immutable or separately copied values if callers must not share nested mutable objects.
9. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| A matching nested key is missing | The implementation keeps only direct matches, or does not descend into the container holding it | Retain nonempty filtered ancestors; add explicit list traversal if the mapping is inside a list |
| A selected parent contains unwanted nested keys | The function copies a matching value without recursing into it | Filter nested values before applying the key-selection rule, as in the main recipe |
| Empty dictionaries unexpectedly disappear | Unmatched parents are preserved only when their filtered child is nonempty | Choose an empty-branch policy and remove the nonempty condition if needed |
TypeError: unhashable type |
A wanted key cannot be placed in a set, or a mapping key violates the expected hashability contract | Use hashable wanted keys; use a predicate when the rule is not set membership |
AttributeError from a key string operation |
A non-string key reached a string-only predicate | Check isinstance(key, str) before calling string methods |
RecursionError |
Input is too deep or contains a cycle | Validate acyclic input and depth, or use an iterative traversal with cycle tracking |
| A custom mapping becomes a plain dict | The implementation accepts Mapping but intentionally constructs {} |
Provide a documented output factory or accept plain-dict output |
| Changing output changes source data | Untraversed mutable values are shared references | Copy those values according to a deliberate copying policy |
10. Tests worth writing
Even a short utility benefits from tests around its contract. Include a direct selected key, a selected grandchild under an unselected branch, a selected key whose own value is a dictionary, and branches with no match. Also cover non-string keys, list-contained dictionaries if supported, empty values, and mapping subclasses when relevant.
data = {"a": 1, "outer": {"keep": 2, "drop": 3}}
assert select_keys(data, {"keep"}) == {"outer": {"keep": 2}}
assert data["outer"]["drop"] == 3 # input was not mutated
nested_match = {"wanted": {"drop": 1, "wanted": 2}}
assert select_keys(nested_match, {"wanted"}) == {"wanted": {"wanted": 2}}
assert select_keys({"empty": {}, "x": 1}, {"empty"}) == {"empty": {}}
11. Or skip the browser setup
If your project also needs website screenshots, you can call ScreenshotNeo directly instead of maintaining browser capture setup. This Python example writes the returned image bytes to a file; see the ScreenshotNeo API documentation for request options.
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)
ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; the response identifies page verdict and billing status in headers. Its MCP server lets Claude, Cursor, and other MCP clients take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
12. FAQ
How do I recursively select dictionary keys in Python?
Loop through data.items(), recursively filter dictionary values, then include a key when it matches or when its filtered child branch contains a match.
Does Python include a built-in recursive key filter?
The cited built-in and collections documentation describes dictionaries and mapping interfaces; the recursive selection policy is a small utility you define for your application.
Should I use dict or Mapping?
Use dict for a focused function that accepts ordinary dictionaries and subclasses. Use Mapping when other mapping implementations should be accepted, and decide what concrete type the result should have.
Will the main function filter dictionaries inside lists?
No. It traverses dictionary values only. Add explicit sequence handling when that is part of the data contract.
Is the original dictionary changed?
No. The function creates new dictionaries along traversed branches, though untraversed mutable values may still be shared.


