findupe

See your duplicate photos side by side, pick what goes, and nothing disappears without your OK.

findupe finds exact duplicates (any file type, zero false positives) and same-photo-different-format duplicates (HEIC / JPEG / RAW, re-encodes, resized exports) on your Mac, then lets you review everything visually in an HTML report before anything moves — to the real macOS Trash, never deleted outright.

Built for photographers: keeping X.CR3 + X.jpg side by side is intentional and is never flagged. Only surplus copies within a format (X copy.jpg, X_2.jpg, a re-imported CR3) become deletion candidates.

Quickstart

pipx install findupe
findupe --demo     # scans a small bundled sample and opens the report — no setup needed

--demo gives you a real report to click through immediately. When you're ready to point it at your own photos, the flow is the same one shown below:

1. findupe scan ~/Pictures/inbox "/Volumes/Extreme SSD/photos" — writes an HTML report.
2. Open the report, check the boxes you agree with (sensible ones are pre-checked), click Export selection.
3. findupe apply <selection>.json --dry-run to preview, then without --dry-run to move the checked files to the Trash (typed confirmation required).
4. findupe undo any time — restores from the Trash by content, not by guessing names.

Nothing is deleted outright: checked files go to the real Trash (recoverable, "Put Back" works), and the last copy of anything always survives — enforced independently of what the report UI shows you.

Install

Requires macOS.

pipx install findupe
# or
uv tool install findupe

Then findupe --help. Running on a non-macOS platform refuses immediately with a clear error — the Trash integration (Finder/AppleScript) and clone-detection notes are macOS/APFS-specific.

Workflow

scan writes two reports — one for images (exact + perceptual matching), one for everything else (PDFs, text, archives, ... — exact-hash matches only, since perceptual matching never applies to non-images). Review and apply each independently.

1. findupe scan ~/Pictures/inbox "/Volumes/Extreme SSD/photos"
2. open report-images.html   # photo/image duplicates — thumbnails, adjust checkboxes
   open report-other.html    # everything else — plain checkbox + path + size rows
3.                           # click "Export selection" on each ->
                              #   findupe-selection-<id>-images.json
                              #   findupe-selection-<id>-other.json
4. findupe apply findupe-selection-<id>-images.json --dry-run   # preview
   findupe apply findupe-selection-<id>-other.json  --dry-run   # preview
5. findupe apply findupe-selection-<id>-images.json            # typed confirmation
   findupe apply findupe-selection-<id>-other.json             # typed confirmation
6. findupe undo                                             # list restore points
   findupe undo <manifest>                                  # put everything back

How it works

findupe flags two kinds of duplicates: files that are byte-for-byte identical, and photos that look like the same shot even across formats or exports (HEIC, JPEG, RAW). It's tuned to leave burst shots and RAW+JPEG pairs alone — those are usually intentional, not duplicates — and everything is re-checked right before anything actually moves, not just at scan time.

Matching tiers, calibration numbers, and the full safety model live in docs/architecture.md.

Documentation

• Reading your report — sections, badges, and flags explained
• Architecture — matching tiers and the full safety model
• FAQ — common questions
• How-to — recipes: multi-root scans, excluding paths, history, stats, undo
• CONTRIBUTING.md — dev setup, commit conventions, release pipeline