---
id: deepmerge
version: "2.1.0"
license: MIT Licence
license_treatment: permissive
maintenance: active
---

# deepmerge — A toolset for deeply merging Python dictionaries.

License: permissive · Maintenance: active · Downloads: 9.8M/mo

## What it is and what it does

deepmerge handles the problem of combining nested Python data structures—dictionaries, lists, and sets—where simple assignment or shallow merging would lose data or overwrite values. It provides both a ready-to-use merger (always_merger) that applies sensible defaults and a Merger class for defining custom merge strategies per type. You specify how lists should combine (append, extend, or replace), how dicts should merge, how sets should combine, and what to do when types conflict or don't match any rule.

The package is lightweight, depends only on typing_extensions, and supports Python 3.8 and later. It's useful in configuration management, data aggregation, and any workflow where you need to combine nested structures without losing information from either source.

Use it for:

- Merge configuration dictionaries from multiple sources (defaults, environment, user config) without losing nested settings.
- Combine API responses or JSON documents with overlapping keys while preserving list elements from both sources.
- Aggregate nested data from multiple files or database records into a single structure.
- Build custom merge logic for domain-specific data types using the Merger class with type-specific strategies.
- Handle YAML or JSON config merging in deployment or build tools where deep nesting is common.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Merges nested Python data structures (dicts, lists, sets) with customizable strategies for handling conflicts and type-specific behavior.

Yes. deepmerge is production-stable (Development Status 5), actively maintained, has no known vulnerabilities, and solves a common problem with minimal dependencies and friction. Install it if you regularly merge nested dicts or need flexible control over how conflicts are resolved.

## Install

pip install deepmerge
uv add deepmerge
poetry add deepmerge

## Installing deepmerge

Before you install: Low install friction with a single pure-Python dependency (typing_extensions). Active maintenance: last release 53 days ago, repository not archived, recent commits present.

License in practice: MIT License (permissive) places no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install deepmerge

from deepmerge import always_merger

base = {"foo": ["bar"]}
next_dict = {"foo": ["baz"]}
result = always_merger.merge(base, next_dict)
# result: {'foo': ['bar', 'baz']}

## Package facts

- License: MIT Licence (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 9.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

merge nested dictionaries, deep merge python dicts, combine nested data structures, recursive dictionary merge, merge lists and dicts together, custom merge strategies, handle nested dict conflicts, data-structures, configuration-management

[View on SkillFed](https://skillfed.io/packages/deepmerge) · [View on PyPI](https://pypi.org/project/deepmerge/)