CSV Diff

CSV Diff is a CLI tool for comparing two CSV files and displaying the results in git diff style.

For example, there are two CSV files, districts-2022.csv and districts-2025.csv. With this tool, you can easily see the data differences between these two CSV files. The output will be saved as a .diff file, like this:

--- districts-2022.csv
+++ districts-2025.csv
@@ -7,9 +7,9 @@
 11.01.07,11.01,Sawang
 11.01.08,11.01,Tapaktuan
 11.01.09,11.01,Trumon
-11.01.10,11.01,Pasi Raja
-11.01.11,11.01,Labuhan Haji Timur
-11.01.12,11.01,Labuhan Haji Barat
+11.01.10,11.01,Pasie Raja
+11.01.11,11.01,Labuhanhaji Timur
+11.01.12,11.01,Labuhanhaji Barat
 11.01.13,11.01,Kluet Tengah
 11.01.14,11.01,Kluet Timur
 11.01.15,11.01,Bakongan Timur
@@ -141,7 +141,7 @@
 11.08.11,11.08,Syamtalira Bayu
 11.08.12,11.08,Tanah Luas
 11.08.13,11.08,Tanah Pasir
-11.08.14,11.08,T. Jambo Aye
+11.08.14,11.08,Tanah Jambo Aye
 11.08.15,11.08,Sawang
 11.08.16,11.08,Nisam
 11.08.17,11.08,Cot Girek
... (truncated)

To see the full differences, please check the result.diff file.

Usage

csvdiff path/to/file1.csv path/to/file2.csv

Use --help to see the available options.

Installation

As an Agent Skill

Install this repository as an AI agent skill using the skills CLI:

npx skills add fityannugroho/csv-diff

This makes csv-diff available as a skill in your AI coding agent (OpenCode, Claude Code, Cursor, Codex, and many others). When you mention comparing CSV files, your agent will know how to use this tool.

What's the difference?

• Skill installation (above): Adds context to your AI agent so it can help you compare CSV files during conversations
• CLI installation (below): Installs the actual command-line tool you run in your terminal

As a CLI Tool

This package is available on PyPI. You can install it as a standalone CLI application using pipx or uv.

Using pipx

pipx install csv-diff-py
csvdiff

Using uv

uv tool install csv-diff-py
csvdiff

or without installing globally, you can use uvx to run it directly:

uvx --from csv-diff-py csvdiff

Development Setup

Prerequisites

• uv package manager
• Python 3.10 or higher

Tip: You can use uv to install Python. See the Python installation guide for more details.

Steps

1. Clone this repository

   git clone https://github.com/fityannugroho/csv-diff.git
   cd csv-diff
   

2. Install dependencies

   uv sync --all-extras
   

3. Run the tool locally

   Via uv:

   uv run csvdiff
   

   Via virtual environment:

   source .venv/bin/activate
   csvdiff
   

4. Run tests

   uv run pytest
   

5. Run linter and formatter

   uv run ruff check
   uv run ruff format
   

Limitations

• Only supports CSV files with a header row.
• CSV files with multi-line cell values (embedded newlines inside quoted fields) are rejected, because they cannot be represented as a valid line-based diff.