Install & Compatibility
Where this runs
tested against v18.1.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.077s · 38MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.9s · import 1.019s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
verify
✓ from approvaltests import verify
Options
✓ from approvaltests import Options
ReportWithBeyondCompare
✓ from approvaltests.reporters.diff_reporters.report_with_beyond_compare import ReportWithBeyondCompare
✗ from approvaltests.reporters import BeyondCompareReporter
Reporter names changed significantly in v17.0.0.
This quickstart demonstrates a basic approval test. Running this code will create a `.received.txt` file with the generated content and, if configured, open an external diff tool (like Beyond Compare or Meld) to compare it against a `.approved.txt` file. On the first run, you'll need to approve the `.received` content, usually by copying it to the `.approved` file via the diff tool. Subsequent runs will pass if the content has not changed.
from approvaltests import verify, Options
def generate_report_content():
return (
"User Report:\n"
"- ID: 123\n"
"- Name: Alice Wonderland\n"
"- Email: alice@example.com\n"
)
# This will generate a .received.txt file and attempt to open a diff tool.
# The first run will likely show a diff, subsequent runs pass if content matches.
verify(generate_report_content())
Debug
Known issues
breakingPrior to v17.0.0, diff reporters were configured differently, often relying on `reporters.json` or direct imports of reporter classes that no longer exist or have been renamed. This can lead to `ImportError` or unexpected reporter behavior when upgrading.fixUpdate reporter imports to use the `ReportWith...` pattern (e.g., `options=Options().with_reporters(ReportWithBeyondCompare)`). Consult the official documentation for the latest reporter names and configuration methods. The `reporters.json` file is still supported for customization but not for built-in reporter definitions.
affects: pre-17.0.0 to 17.0.0+
gotchaApprovalTests relies on external diff tools (like Beyond Compare, Meld, KDiff3, VS Code diff) to compare received and approved files. If no diff tool is detected or configured, approval tests might not open a comparison window, or fail with a 'no reporter found' message, potentially leading to unnoticed changes or manual file comparison.fixEnsure a diff tool is installed on your system and configured for ApprovalTests. This often involves ensuring the tool is in your system's PATH, setting environment variables, or creating a `reporters.json` file. Check the 'Reporters' section of the ApprovalTests documentation for setup instructions.
affects: All versions
breakingVersion 17.4.2 had a packaging error that prevented it from being imported, leading to an `ImportError` or `ModuleNotFoundError` immediately after installation, making the library unusable.fixUpgrade to version 17.4.3 or later: `pip install --upgrade approvaltests`. This issue was resolved in the subsequent patch release.
affects: 17.4.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'approvaltests'
If this occurs after `pip install approvaltests`, it's likely due to a packaging error in version 17.4.2.
fixUpgrade to the latest version: `pip install --upgrade approvaltests` (to get 17.4.3 or newer).
No reporter found for file: your_test_name.received.txt
ApprovalTests could not find or launch a suitable diff tool to display the comparison between the received and approved files.
fixInstall a supported diff tool (e.g., Beyond Compare, Meld, VS Code) and ensure it's configured correctly according to the ApprovalTests documentation (e.g., in your PATH or via `reporters.json`).
ImportError: cannot import name 'BeyondCompareReporter' from 'approvaltests.reporters'
You are attempting to import a reporter class using an old path or name that was changed in v17.0.0.
fixUpdate your import statement and reporter usage. For Beyond Compare, use `from approvaltests.reporters.diff_reporters.report_with_beyond_compare import ReportWithBeyondCompare` and pass it to `Options().with_reporters(...)`.
Upgrade
Version history
18.1.1latest on PyPI · released Jun 15, 2026
Audit
Dependencies
No dependency data recorded yet.