mergedeep is a Python library providing a deep merge function for dictionaries and other mutable mappings. It offers flexible strategies for handling conflicts, including replacement (default), additive merging for collections like lists, and type-safe replacement. The current version is 1.3.4, and the library is actively maintained with regular releases.
Install & Compatibility
Where this runs
tested against v1.3.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.015s · 17.8MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.5s · import 0.012s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
merge
✓ from mergedeep import merge
✗ import mergedeep; mergedeep.merge(...)
The primary merge function `merge` is typically imported directly.
Strategy
✓ from mergedeep import merge, Strategy
Import `Strategy` enum if custom merge strategies are needed.
Demonstrates basic deep merging using the default REPLACE strategy and an example of the ADDITIVE strategy for collections. It shows both non-mutating and mutating merge patterns.
from mergedeep import merge, Strategy
a = {'keyA': 1, 'nested': {'x': 10, 'list_data': [1, 2]}}
b = {'keyB': 2, 'nested': {'y': 20, 'list_data': [3, 4]}}
c = {'keyC': 3, 'nested': {'x': 100, 'new_list': [5]}}
# 1. Merge into a new dictionary (non-mutating)
merged_new = merge({}, a, b, c)
print(f"Merged into new: {merged_new}")
# Expected: {'keyA': 1, 'nested': {'x': 100, 'list_data': [3, 4], 'y': 20, 'new_list': [5]}, 'keyB': 2, 'keyC': 3}
# 2. Merge into an existing dictionary (mutating 'a')
merge(a, b, c)
print(f"Merged into existing 'a': {a}")
# Expected: {'keyA': 1, 'nested': {'x': 100, 'list_data': [3, 4], 'y': 20, 'new_list': [5]}, 'keyB': 2, 'keyC': 3}
# 3. Merging with an additive strategy for lists
dst_additive = {'items': [1, 2], 'counts': {'a': 1}}
src_additive = {'items': [3, 4], 'counts': {'b': 1}}
merged_additive = merge({}, dst_additive, src_additive, strategy=Strategy.ADDITIVE)
print(f"Merged with ADDITIVE strategy: {merged_additive}")
# Expected: {'items': [1, 2, 3, 4], 'counts': {'a': 1, 'b': 1}}
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mergedeep'
The 'mergedeep' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install mergedeep'.
ImportError: cannot import name 'merge' from 'mergedeep'
The 'mergedeep' package is not installed or the import statement is incorrect.
fixEnsure the package is installed and use the correct import statement: 'from mergedeep import merge'.
TypeError: destination type: <class 'list'> differs from source type: <class 'set'> for key: "key"
Attempting a typesafe merge with mismatched types between destination and source values.
fixEnsure that the destination and source values are of the same type when using typesafe merge strategies.
TypeError: Cannot merge type <class 'set'> with <class 'list'> using strategy TYPESAFE_REPLACE.
When using `Strategy.TYPESAFE_REPLACE`, `mergedeep` encounters a conflict where a key exists in both dictionaries but with values of incompatible types (e.g., a set and a list), and `TYPESAFE_REPLACE` explicitly prevents such type mismatches.
fixfrom mergedeep import merge, Strategy
dst = {"key": [1, 2]}
src = {"key": {"a", "b"}} # Example: trying to merge a set into a list key
# To resolve, either ensure types are compatible or use a different strategy:
# Option 1: Adjust source type if possible
# src = {"key": [3, 4]}
# merge(dst, src, strategy=Strategy.TYPESAFE_REPLACE)
# Option 2: Use Strategy.REPLACE to overwrite with the new type
merge(dst, src, strategy=Strategy.REPLACE)
print(dst) # Output: {'key': {'a', 'b'}}
# Option 3: Use Strategy.ADDITIVE to combine collections if applicable
# This example still raises TypeError because set and list are incompatible for ADDITIVE
# If both were lists, ADDITIVE would extend the list.
# dst = {"key": [1, 2]}
# src = {"key": [3, 4]}
# merge(dst, src, strategy=Strategy.ADDITIVE)
# print(dst) # Output: {'key': [1, 2, 3, 4]} TypeError: cannot pickle '_thread.lock' object
`mergedeep` uses `deepcopy` internally for nested mutable objects, and one of the objects within your dictionaries is not picklable (e.g., a thread lock, file handle, or other non-serializable object).
fixEnsure that all objects within the dictionaries you are merging are picklable. If an object is inherently not picklable, you must remove it from the dictionaries before calling `mergedeep.merge` or implement custom pre-processing to handle such types.
Audit
Dependencies
No dependency data recorded yet.