CSV Diff

1.2 · active · verified Sun Apr 12

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.

Warnings

gotcha Providing a `key_columns` (or `key` parameter for `load_csv`) is crucial. Without a specified unique key, `csv-diff` cannot accurately identify matching rows for comparison, potentially leading to incorrect diff results or errors. This was explicitly addressed with a fix in version 1.0.
Fix: Always provide the `--key` option when using the CLI, or the `key` parameter to `load_csv` when using the library.
breaking Prior to version 1.0, column names containing a `.` character could cause bugs. This was fixed in 1.0, potentially changing diff results for users who encountered this issue in earlier versions.
Fix: Ensure your `csv-diff` version is 1.0 or newer. If you relied on the old (buggy) behavior, review your diffs after updating.
gotcha While `csv-diff` automatically detects CSV/TSV/JSON formats, it's safer to explicitly specify the input format using `--format=csv`, `--format=tsv`, or `--format=json` for the CLI, or appropriate handling when loading data programmatically, especially for ambiguous files.
Fix: Use the `--format` CLI option or ensure your data loading logic explicitly handles the expected input format to avoid unexpected parsing behavior.
deprecated The format of the human-readable CLI output changed significantly in versions 0.3.1 and 0.2 (e.g., order of output, inclusion of more detail). Scripts that parsed the CLI's plain text output in older versions might break or produce incorrect results with newer versions.
Fix: For programmatic consumption of diff results, use the dictionary output from the `compare` function rather than parsing the CLI's human-readable text output. If you must parse CLI output, ensure your parsing logic is robust to format changes or use `--json` output.

Install

pip install csv-diff Install stable version

Imports

load_csv
```
from csv_diff import load_csv, compare
```
Used to load CSV/TSV/JSON data from a file-like object or path into a standardized dictionary format for comparison.
compare
```
from csv_diff import load_csv, compare
```
The main function for performing the diff between two loaded data structures.

Quickstart

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')}")

view raw JSON →