A Python CLI wrapper for czkawka-cli that simplifies finding and organizing duplicate files and similar images.
- Duplicate File Detection: Find exact duplicate files based on content hash
- Similar Image Detection: Find visually similar images with configurable similarity threshold
- Organized Output: Automatically groups and moves duplicates to a destination directory with unique identifiers
- Dry Run Mode: Preview what would happen without making any changes
- Human-Readable Output: Clean tabular display for similar images with dimensions, size, and similarity scores
- Python 3.10+
- czkawka-cli must be installed and available in your PATH
-
Clone the repository:
git clone https://github.com/yourusername/hiccup-remedy.git cd hiccup-remedy -
Install dependencies using Pipenv:
pipenv install
python hiccup_remedy.py [OPTIONS] DIR [DIR ...]| Argument | Description |
|---|---|
DIR |
One or more directory paths to scan for duplicates |
| Option | Description | Default |
|---|---|---|
-m, --mode {dup,image} |
Mode of operation: dup for duplicate files, image for similar images |
dup |
-d, --dest PATH |
Destination directory for moved duplicates | Current directory |
-n, --dry-run |
Preview results without moving any files | Disabled |
Find duplicate files (dry run):
python hiccup_remedy.py -n ~/Downloads ~/DocumentsMove duplicate files to a specific directory:
python hiccup_remedy.py -d ~/duplicates ~/Downloads ~/DocumentsFind similar images:
python hiccup_remedy.py -m image -n ~/PicturesMove similar images to a destination:
python hiccup_remedy.py -m image -d ~/similar_images ~/Pictures- Scans the specified directories using
czkawka-cli - Parses the output to group duplicate/similar files
- Each group is assigned a unique UUID
- Files are moved to
<dest>/<uuid>/with flattened filenames preserving their original relative paths
hiccup-remedy/
├── hiccup_remedy.py # Main CLI entry point
├── util.py # Utility functions (human-readable file sizes)
├── Pipfile # Python dependencies
└── hiccup/
├── finder.py # Core finder logic wrapping czkawka-cli
└── filegroup.py # File group classes for duplicates and similar images
- sh - Python subprocess interface
- prettytable - ASCII table formatting