This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
kapowarr-dedup — Setup & Usage
A single stdlib-only Python script (dedup.py). No install, no dependencies.
Requirements
- Python 3
- A running Kapowarr instance and its API key (Kapowarr → Settings → General → API key)
Configuration (environment variables)
| Variable | Default | Meaning |
|---|---|---|
KAPOWARR_API_KEY |
— (required) | Your Kapowarr API key |
KAPOWARR_URL |
http://192.168.1.209:5656 |
Base URL of your Kapowarr instance |
DEDUP_DRY_RUN |
1 |
1 = report only; 0 = actually delete |
DEDUP_OUTLIER_RATIO |
3 |
Skip+report an issue if its largest file is more than this × the next-largest |
DEDUP_OUTLIER_MIN_MB |
90 |
…and only if that largest file also exceeds this size (avoids flagging "good issue + tiny broken partial") |
Usage
1. Dry run first (changes nothing — always do this):
KAPOWARR_API_KEY=yourkey python3 dedup.py
It prints how many issues have duplicates, how many files would be deleted, the space reclaimed, and any outlier issues it's skipping for you to eyeball.
2. Execute once you're happy with the report:
KAPOWARR_API_KEY=yourkey DEDUP_DRY_RUN=0 python3 dedup.py
Notes
- Keep rule: the largest file per issue is kept (most complete scan); smaller partial/broken copies are deleted.
- Outlier guard: issues whose biggest file is suspiciously large (a likely mis-matched multi-issue bundle) are skipped and listed, never auto-deleted — review those by hand.
- Deleting one duplicate cascades in Kapowarr (it tidies an issue's sibling files together), so a run may report many
404s for files already removed — that's expected, not an error. - No content is ever lost: every issue always keeps at least one file.