Compare two drives and find duplicate files. Zero dependencies, cross-platform, with undo.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for wlkns from gravatar.com wlkns

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Wilkins Morales
  • Tags cli , cross-platform , deduplication , drive-comparison , file-management
  • Requires: Python >=3.8
  • Provides-Extra: rich
Classifiers
Report project as malware

Project description

diskcomp

CI PyPI version Python versions License: MIT GitHub release Platform support Standalone binaries

Find and safely delete duplicate files โ€” across two drives or within one. Zero dependencies, cross-platform, with undo.

๐Ÿ“‹ View the Roadmap โ€” See what's planned for future versions

โœจ Key Features

  • ๐Ÿ” Smart Detection โ€” SHA256 hashing finds true duplicates regardless of filename
  • โšก Performance โ€” Two-pass scan: filter by size first, hash only size-collision candidates
  • ๐Ÿ›ก๏ธ Safety First โ€” Always ask before deleting, create undo logs, detect read-only files
  • ๐Ÿ–ฅ๏ธ Cross-Platform โ€” macOS, Linux, Windows with native progress bars (Rich UI + ANSI fallback)
  • ๐Ÿ“Š Rich Reports โ€” CSV/JSON output with file paths, sizes, hashes, and deletion recommendations
  • ๐ŸŽฏ Flexible Modes โ€” Compare two drives, clean single drive, interactive deletion, batch operations
  • โš™๏ธ Zero Dependencies โ€” Pure Python, optional Rich UI, works everywhere Python runs
  • ๐Ÿ“ฆ Multiple Install Options โ€” pip, pipx, standalone binaries (Homebrew coming in v1.1)

๐Ÿ“Š Project Status

diskcomp 1.0.0 is production-ready and actively maintained. The core deduplication engine has been tested with 285 comprehensive tests covering edge cases, cross-platform compatibility, and error handling.

  • โœ… Feature Complete โ€” All planned v1.0 features implemented
  • โœ… Well Tested โ€” 285 tests, CI on 3 platforms ร— 3 Python versions
  • โœ… Production Ready โ€” Used for real data cleanup with safety guarantees
  • โœ… Cross-Platform โ€” Native builds for macOS, Linux, Windows
  • โœ… Multiple Distribution Channels โ€” PyPI, GitHub Releases (Homebrew coming in v1.1)

Quick Install

Download binary (no Python required):

macOS:

# Direct download (recommended)
curl -L -o diskcomp https://github.com/w1lkns/diskcomp/releases/latest/download/diskcomp-macos
chmod +x diskcomp
./diskcomp --help

# Homebrew (coming in v1.1)
# brew tap w1lkns/diskcomp
# brew install diskcomp

Linux:

# Download directly  
curl -L -o diskcomp https://github.com/w1lkns/diskcomp/releases/latest/download/diskcomp-linux
chmod +x diskcomp
./diskcomp --help

Windows:

# Download diskcomp-windows.exe from GitHub Releases
# https://github.com/w1lkns/diskcomp/releases/latest
diskcomp-windows.exe --help

Python install (if you have Python):

pipx (recommended โ€” handles PATH automatically):

pipx install diskcomp
diskcomp --help

Don't have pipx? brew install pipx on macOS, pip install pipx elsewhere.

pip install:

pip install diskcomp
diskcomp --help

Single-file version (no install, no dependencies):

curl -O https://raw.githubusercontent.com/w1lkns/diskcomp/main/diskcomp.py
python3 diskcomp.py --help

Quick Start

Interactive mode (no arguments โ€” clears screen, shows menu):

diskcomp

The launch menu offers:

  1) Compare two drives
  2) Clean up a single drive
  3) Load previous report
  4) Help
  5) Quit

Compare two drives (command-line):

diskcomp --keep /Volumes/backup --other /Volumes/external

Clean up a single drive (find internal duplicates):

diskcomp --single /Volumes/my-drive

Dry-run (count files without hashing):

diskcomp --keep /path/A --other /path/B --dry-run

Load a previous report (skip re-scanning):

diskcomp --delete-from ./diskcomp-report-20260322-235800.csv

๐Ÿ“Š Example Output

Interactive mode startup:

 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ•—  โ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ•—   โ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—
 โ–ˆโ–ˆโ•”โ•โ•โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ•โ•โ•โ–ˆโ–ˆโ•‘ โ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•”โ•โ•โ•โ•โ•โ–ˆโ–ˆโ•”โ•โ•โ•โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ–ˆโ–ˆโ•—
 โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ• โ–ˆโ–ˆโ•‘     โ–ˆโ–ˆโ•‘   โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ–ˆโ–ˆโ–ˆโ–ˆโ•”โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•
 โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ•šโ•โ•โ•โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•— โ–ˆโ–ˆโ•‘     โ–ˆโ–ˆโ•‘   โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ•šโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ•โ•
 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•—โ•šโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ•šโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘ โ•šโ•โ• โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘
 โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•โ•šโ•โ•โ•โ•โ•โ•โ•โ•šโ•โ•  โ•šโ•โ• โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•     โ•šโ•โ•โ•šโ•โ•

 Find duplicates. Free space. Stay safe.
 v1.0.0

What would you like to do?
  1) Compare two drives
  2) Clean up a single drive  
  3) Load previous report
  4) Help
  5) Quit

Progress display:

Drive Health: Keep=/Volumes/Photos (2TB APFS), Other=/Volumes/Backup (4TB NTFS)
Scanning: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1,847 files found
Hashing candidates: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 234/234 files (23.4 MB/s)

Found 42 duplicates. You could free 1.2 GB from /Volumes/Backup. Ready to review?

๐Ÿ›ก๏ธ Safety Guarantees

Interactive mode startup:

 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ•—  โ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ•—   โ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—
 โ–ˆโ–ˆโ•”โ•โ•โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ•โ•โ•โ–ˆโ–ˆโ•‘ โ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•”โ•โ•โ•โ•โ•โ–ˆโ–ˆโ•”โ•โ•โ•โ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ•— โ–ˆโ–ˆโ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ–ˆโ–ˆโ•—
 โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ• โ–ˆโ–ˆโ•‘     โ–ˆโ–ˆโ•‘   โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ–ˆโ–ˆโ–ˆโ–ˆโ•”โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•
 โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ•šโ•โ•โ•โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•— โ–ˆโ–ˆโ•‘     โ–ˆโ–ˆโ•‘   โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘โ•šโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•”โ•โ•โ•โ•
 โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘  โ–ˆโ–ˆโ•—โ•šโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•—โ•šโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ•”โ•โ–ˆโ–ˆโ•‘ โ•šโ•โ• โ–ˆโ–ˆโ•‘โ–ˆโ–ˆโ•‘
 โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•โ•šโ•โ•โ•โ•โ•โ•โ•โ•šโ•โ•  โ•šโ•โ• โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•โ•โ•โ•โ• โ•šโ•โ•     โ•šโ•โ•โ•šโ•โ•

 Find duplicates. Free space. Stay safe.
 v1.0.0

What would you like to do?
  1) Compare two drives
  2) Clean up a single drive  
  3) Load previous report
  4) Help
  5) Quit

Progress display:

Drive Health: Keep=/Volumes/Photos (2TB APFS), Other=/Volumes/Backup (4TB NTFS)
Scanning: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1,847 files found
Hashing candidates: โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 234/234 files (23.4 MB/s)

Found 42 duplicates. You could free 1.2 GB from /Volumes/Backup. Ready to review?

Your files are safe. diskcomp prioritizes safety over convenience:

  • ๐Ÿ”’ No Automatic Deletion โ€” Every file deletion requires explicit user confirmation
  • ๐Ÿ“ Undo Logs โ€” Complete audit trail written before any file is deleted
  • โš ๏ธ Read-Only Detection โ€” Automatically detects and warns about read-only drives
  • ๐Ÿ” Dry-Run Mode โ€” Preview operations without any file system changes
  • โน๏ธ Abort Anytime โ€” Press Ctrl+C at any prompt to stop safely
  • โœจ Interactive Mode โ€” Review each file individually before deletion
  • ๐Ÿ” SHA256 Verification โ€” Cryptographic hashing ensures only true duplicates are identified

Usage & Flags

Flag Description Example
--keep PATH Path to the "keep" drive (files to retain). Required unless interactive. --keep /Volumes/backup
--other PATH Path to the "other" drive (duplicates deleted from here). Required unless interactive. --other /Volumes/external
--single PATH Scan one drive for internal duplicates (redundant copies on the same drive). --single /Volumes/photos
--dry-run Walk and count files without hashing (quick preview). --dry-run
--limit N Hash only first N files per drive (testing only). --limit 100
--output PATH Custom report path (default: ~/diskcomp-report-YYYYMMDD-HHMMSS.csv). --output ./my-report.csv
--format csv|json Report format: csv or json (default: csv). --format json
--min-size SIZE Minimum file size to include (default: 1KB). Accepts bytes, KB, MB, GB. --min-size 10MB
--delete-from PATH Load an existing report and start deletion workflow (skip re-scanning). --delete-from ./diskcomp-report-20260322.csv
--undo PATH View the audit log of a previous deletion session. --undo ./diskcomp-undo-20260322.json

How It Works

  1. Drive Health Checks (pre-scan, two-drive mode):

    • Space summary for both drives
    • Filesystem detection (HFS+, NTFS, ext4, exFAT, etc.)
    • Read-only detection (warns if "keep" drive is read-only)
    • Read speed benchmark (128MB)
    • Optional SMART data (if smartmontools available)

  2. Scanning & Hashing:

    • Walks drives recursively
    • Skips OS noise (.DS_Store, Thumbs.db, System Volume Information, etc.)
    • Two-pass optimization: size-filter candidates first, then SHA256 hash
    • Live progress bar with speed and ETA

  3. Reporting:

    • CSV or JSON report saved to ~/diskcomp-report-YYYYMMDD-HHMMSS.{csv,json}
    • Atomic writes (temp โ†’ rename, safe against crashes mid-write)

  4. Deletion Workflow (optional):

    • Mode A (Interactive): Shows both copies numbered (1) and (2) โ€” you pick which to delete, skip, or abort. Running space freed shown after each deletion.
    • Mode B (Batch): Dry-run preview with file type breakdown โ†’ type DELETE to confirm โ†’ progress bar
    • Undo log written before each deletion (audit-first pattern)
    • Always abortable with Ctrl+C
    • Can re-run from a saved report without re-scanning (option 3 in menu or --delete-from)

  5. Undo Log (--undo flag):

    • JSON file listing all deleted files with paths, sizes, hashes, and timestamps
    • Deletion is permanent โ€” the log is an audit trail, not a restore mechanism

Reports

CSV format (default, spreadsheet-friendly):

status,original_file,duplicate_file,size_mb,verification_hash
DELETE_FROM_OTHER,/Volumes/keep/photos/pic1.jpg,/Volumes/other/photos/pic1.jpg,2.5,abc123...
UNIQUE_IN_KEEP,/Volumes/keep/docs/resume.pdf,,0.1,def456...
UNIQUE_IN_OTHER,,/Volumes/other/temp/junk.tmp,5.0,ghi789...
Column Values
status DELETE_FROM_OTHER, UNIQUE_IN_KEEP, UNIQUE_IN_OTHER
original_file Path to the copy to keep
duplicate_file Path to the copy to delete
size_mb File size in MB
verification_hash SHA256 hex string

JSON format (programmatic use):

diskcomp --keep /Volumes/keep --other /Volumes/other --format json

Known Limitations

NTFS Drives on macOS and Linux

NTFS (Windows filesystem) drives are read-only on macOS and Linux by default:

  • diskcomp can scan and identify duplicates on NTFS drives
  • diskcomp cannot delete files from NTFS drives without a third-party driver

Workaround:

diskcomp detects this and warns during health checks.

Optional Enhancements

Rich library โ€” professional progress bars and color styling:

pip install diskcomp[rich]

smartmontools โ€” enables SMART data display:

  • macOS: brew install smartmontools
  • Linux: apt-get install smartmontools or pacman -S smartmontools
  • Windows: wmic logicaldisk (built-in, no install needed)

Without these, diskcomp uses ANSI progress bars and skips SMART data.

Cross-Platform Testing

CI validates diskcomp on 9 combinations:

  • macOS (latest) ร— Python 3.8, 3.10, 3.12
  • Linux (Ubuntu latest) ร— Python 3.8, 3.10, 3.12
  • Windows (latest) ร— Python 3.8, 3.10, 3.12

All tests pass and the single-file build is verified on each combination.

Development

Run tests locally:

python -m pytest tests/

Generate single-file version:

python build_single.py
python diskcomp.py --help

๐Ÿค Support & Contributing

โญ Like diskcomp? Star it on GitHub to show support!

License

MIT โ€” See LICENSE file for details.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for wlkns from gravatar.com wlkns

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: Wilkins Morales
  • Tags cli , cross-platform , deduplication , drive-comparison , file-management
  • Requires: Python >=3.8
  • Provides-Extra: rich
Classifiers

Release history Release notifications | RSS feed

This version

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

diskcomp-1.0.4.tar.gz (96.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

diskcomp-1.0.4-py3-none-any.whl (55.8 kB view details)

Uploaded Python 3

File details

Details for the file diskcomp-1.0.4.tar.gz.

File metadata

  • Download URL: diskcomp-1.0.4.tar.gz
  • Upload date:
  • Size: 96.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for diskcomp-1.0.4.tar.gz
Algorithm Hash digest
SHA256 1bb6d27b4d2b9e492ff0110a403f027011efb13ec8c653adf6587728e7bba982
MD5 232a9182b25e460ea87c5548e1db5b37
BLAKE2b-256 d6b65951444a4cb813b643fc7c0fbda4d5fdad1357c023a5e762fe060cc9a3fc

See more details on using hashes here.

File details

Details for the file diskcomp-1.0.4-py3-none-any.whl.

File metadata

  • Download URL: diskcomp-1.0.4-py3-none-any.whl
  • Upload date:
  • Size: 55.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.3

File hashes

Hashes for diskcomp-1.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 0ca05d323f21bfea0db9bb6461fdd65445f2a22cb10b816bf09f47b586723e90
MD5 5f14fd94eff6177bc47ce2eacd4abaf7
BLAKE2b-256 a40b8c41ba95ff041c8d66bc005c523eb29e789cd116a793128f085f26e0e52c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page