kapowarr-dedup

Remove duplicate issue files from a Kapowarr comic library — keep the best copy of each issue, delete the redundant ones, all through Kapowarr's own API.

Kapowarr can accumulate several files for the same issue — auto-grabbed releases that pile up as ... (1).cbz, ... (2).cbz, ... (3).cbz. This walks every matched issue, keeps the largest file (the most complete scan), and deletes the smaller partial/broken duplicates. It's dry-run by default, so you always see what it would do before anything is removed.

Why does this happen, and why "keep the largest"?

When auto-search grabs more than one release for an issue, Kapowarr keeps them all under the issue. The extra copies are usually either identical re-grabs or incomplete/broken downloads (a few hundred KB instead of tens of MB). The largest file is almost always the real, complete scan — so that's the keeper, and the rest are safe to drop. Deleting one duplicate cascades in Kapowarr (it tidies an issue's sibling files together), so the cleanup converges quickly.

The outlier guard (so it never deletes the wrong thing)

Occasionally the largest file is the wrong one — e.g. a whole-volume bundle that got mis-matched to a single issue (200 MB where the real issue is 30 MB). To avoid keeping that and deleting the correct copies, any issue whose biggest file is both far larger than the next and over an absolute size threshold is skipped and reported for you to review by hand, never auto-pruned.

What it does

• Keeps the largest file per issue, removes redundant duplicates via the Kapowarr API
• Dry-run by default — reports issues affected, files to delete, and space reclaimed
• Outlier guard — skips + reports suspicious oversized files instead of risking a wrong delete
• Stdlib-only Python, no dependencies

Roadmap

• Optional "prefer format" tie-breaker (e.g. CBZ over CBR at equal size)
• Per-volume scoping for targeted runs

Built with Claude

This tool was built with the help of Claude (Anthropic's Claude Opus 4.8).

License

GPL-3.0-or-later. Copyleft — share improvements forward.