---
id: pytest-icdiff
version: "0.9"
license: Unlicense
license_treatment: permissive
maintenance: dormant
---

# pytest-icdiff — use icdiff for better error messages in pytest assertions

License: permissive · Maintenance: dormant · Downloads: 9.7M/mo

## What it is and what it does

pytest-icdiff is a pytest plugin that hooks into assertion failures and replaces pytest's default diff output with ICDiff's colored, side-by-side comparison format. When an `assert ==` fails, instead of seeing a linear diff, you get a structured, color-coded view that makes it easier to spot differences at a glance, especially for complex data structures or multi-line strings.

The plugin requires pytest, icdiff, and pprintpp as runtime dependencies and installs with low friction. It activates automatically once installed—no configuration needed. Maintenance is dormant (no updates since late 2023), but the codebase is stable and compatible with Python 3.7 through 3.11. There are no known security vulnerabilities.

Use it for:

- Debugging test failures involving complex nested data structures where visual clarity matters.
- Comparing multi-line strings or formatted output in assertion failures.
- Making test output more readable in CI/CD logs where color-coded diffs are easier to scan.
- Improving developer experience during local test runs with better visual feedback on assertion mismatches.

## Worth the install?

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

A pytest plugin that replaces default assertion diff output with colored, side-by-side diffs from ICDiff for easier comparison of mismatched values.

Yes, if you run pytest regularly and want clearer assertion diffs. Installation is frictionless, the license is unrestricted, and there are no security concerns. The dormant maintenance status is a minor consideration—the plugin is stable and unlikely to need updates unless pytest itself changes its assertion internals—but monitor compatibility if you upgrade pytest to versions well beyond 2024.

## Install

pip install pytest-icdiff
uv add pytest-icdiff
poetry add pytest-icdiff

## Installing pytest-icdiff

Before you install: Low friction install with three lightweight runtime dependencies (pytest, icdiff, pprintpp). Maintenance is dormant—last release was 2023-12-05 and no commits since 2024-09-04—but the repository is not archived and the plugin remains compatible with current Python versions (3.7–3.11).

License in practice: Distributed under the Unlicense (public domain), so there are no licensing restrictions on use, modification, or distribution.

Quickstart:

pip install pytest-icdiff

# Then run pytest normally; the plugin activates automatically
pytest test_file.py

Verify before relying:

- Whether the plugin works correctly with pytest versions released after 2024-09-04.
- Performance impact on test suites with many assertion failures.

## Package facts

- License: Unlicense (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 9.7M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest assertion diff formatting, better pytest error messages, colored side-by-side diffs, pytest icdiff plugin, improve pytest output readability, pytest-plugin, test-output-formatting

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