csv-diff is a Python CLI tool and library for efficiently comparing the semantic contents of two CSV, TSV, or JSON files. It identifies added, removed, and changed rows based on a specified key, ignoring cosmetic differences like row and column ordering. The library is actively maintained with regular updates addressing features and bug fixes, with its current version being 1.2.
Install & Compatibility
Where this runs
tested against v1.2 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.012s · 18.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.012s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Used to load CSV/TSV/JSON data from a file-like object or path into a standardized dictionary format for comparison.
from csv_diff import load_csv, compare
The main function for performing the diff between two loaded data structures.
from csv_diff import load_csv, compare
This quickstart demonstrates how to use `csv-diff` programmatically to compare two in-memory CSV datasets. It loads the data using `load_csv`, specifying 'id' as the unique key, and then uses `compare` to generate a dictionary detailing added, removed, and changed rows and columns.
import io
from csv_diff import load_csv, compare
# Simulate two CSV files as in-memory strings
csv1_data = """id,name,age
1,Alice,30
2,Bob,24
3,Charlie,35"""
csv2_data = """id,name,age
1,Alice,31
3,Charlie,35
4,David,28"""
# Load the CSV data, specifying the key column
csv1 = load_csv(io.StringIO(csv1_data), key="id")
csv2 = load_csv(io.StringIO(csv2_data), key="id")
# Compare the two CSVs
diff = compare(csv1, csv2)
# Print the detected differences
print(f"Added rows: {diff.get('added')}")
print(f"Removed rows: {diff.get('removed')}")
print(f"Changed rows: {diff.get('changed')}")
print(f"Columns added: {diff.get('columns_added')}")
print(f"Columns removed: {diff.get('columns_removed')}")
csv-diff --version
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.