Cleanup
Cleanup
Section titled “Cleanup”The Cleanup page (Settings → Cleanup) provides five fixed automated operations that remove unnecessary subtitle files and database entries from your library, plus two opt-in rules covering embedded video tracks.
Operations
Section titled “Operations”Each operation has the same shape: a config card, a dry-run preview, and a Run Now button. None of them touch the database or filesystem until you confirm.
Language Filter
Section titled “Language Filter”What it does. Walks every video folder in your library and deletes subtitle sidecars whose language token isn’t in your keep-list.
What signals deletion. The language token in the sidecar filename
must not appear in the configured list. Filenames are parsed by the
same grammar Sublarr uses elsewhere — Episode.S01E01.de.ass is
recognised as de, Episode.S01E01.de.hi.ass is recognised as de
with the hi modifier, and the whole sidecar is dropped if de isn’t
on the keep-list.
Example. Keep-list de,en. The folder contains *.de.ass,
*.en.srt, *.ja.ass, *.fr.srt → the .ja.ass and .fr.srt
sidecars get moved to the trash directory. und (undetermined
language) sidecars are kept by default; toggle the Drop und sidecars
config flag to remove those too.
Config. Comma-separated language codes (de,en). Order doesn’t
matter; the comparison is case-insensitive. An empty keep-list aborts
the run instead of deleting everything — Sublarr refuses to nuke every
sidecar in the library on a misconfiguration.
Format Upgrade
Section titled “Format Upgrade”What it does. When the same logical subtitle exists as both .srt
and .ass, deletes the .srt copy.
What signals deletion. Two sidecars share the same (language, modifiers) token grammar but different containers. The richer
container (.ass / .ssa) wins; the plain .srt is trashed. The
file pair must live in the same folder — Sublarr won’t compare across
directories.
Example. Episode.S01E01.de.srt and Episode.S01E01.de.ass exist
side-by-side → .srt goes to trash, .ass stays. If only one of the
two exists, nothing happens.
Orphan Files
Section titled “Orphan Files”What it does. Deletes subtitle sidecars whose video file is gone.
What signals deletion. A sidecar’s parent video can’t be found.
Sublarr looks for any video file in the same folder with a matching
basename (modulo language token), e.g. Episode.S01E01.de.ass
expects Episode.S01E01.<videoExt> in the same directory. If no
candidate exists in any of the supported video extensions
(.mkv, .mp4, .avi, …) the sidecar is treated as orphaned.
Why this happens. The user moved or renamed media outside Sublarr, the *arr replaced a file with a different episode-number scheme, or a manual rsync left old subs behind.
Orphan DB Entries
Section titled “Orphan DB Entries”What it does. Removes rows from the wanted_items and
subtitle_history tables when the file they reference no longer
exists on disk.
What signals deletion. os.path.exists() returns False for the
recorded file_path. The database row is removed regardless of how
old it is — there’s no retention window.
When you’d run it. After a bulk filesystem reorganisation, after restoring a backup that’s older than the database, or as a pre-deduplication housekeeping pass.
Old Backups
Section titled “Old Backups”What it does. Deletes remux backup files (*.mkv.bak) older than
the retention window.
What signals deletion. File mtime is older than
remux_backup_retention_days (default 7). The
Subtitle Backups section below
manages a different fleet (*.bak.<ext> next to subtitles); this
operation only touches container-level remux backups created by the
remux to add subtitle stream path.
Additional Opt-In Rules
Section titled “Additional Opt-In Rules”Beyond the five fixed operations above, Sublarr ships two rules that are off by default and touch embedded video tracks rather than sidecar files: Signs & Forced Removal strips non-dialogue (signs / forced / songs) tracks, and Foreign-Track Removal, covered in detail below. Both move removals to the trash and stay recoverable — nothing here is a hard delete.
Foreign-Track Removal
Section titled “Foreign-Track Removal”What it does. Strips embedded subtitle streams from a video container whose language isn’t in the keep-set. Audio streams are never touched — only subtitle tracks are ever removed, so a Russian/Polish/Japanese audio track stays exactly where it is even after its subtitle counterpart is stripped.
How it works. Sublarr probes the container with ffprobe, then
remuxes it with mkvmerge (falling back to ffmpeg if mkvmerge isn’t
installed) into a temporary file, verifies the result, and atomically
swaps it in. The original file is never overwritten in place — it’s
moved to the trash directory as <file>.<timestamp>.bak, fully
restorable.
Two independent triggers, one engine. Both paths below call the same stripping engine, but resolve the keep-set differently:
| Trigger | Where to configure | Keep-set |
|---|---|---|
| Automatic, right after a subtitle download or an embedded-subtitle extract | Settings → Subtitle Automation → Foreign-Track Cleanup — Strip by default toggle | The item’s own target/missing languages ∪ the global always-keep list (cleanup_foreign_tracks_keep_languages, default de,en — not exposed in the UI, only via the config API). This means a download for just de still preserves English tracks. |
| Manual / scheduled, against your whole library at once | Settings → Cleanup → Foreign-Track Removal card on this page | A fixed list you set on the rule itself (Behalten tags), applied identically to every video the scan finds, regardless of what was originally downloaded for it. |
Config (both surfaces).
| Setting | Default | Effect |
|---|---|---|
| Keep languages | de,en | Comma-separated (or tag-picker) list of languages whose subtitle tracks survive. Expanded to every known variant of a tag, so de also matches deu/ger as reported by ffprobe. |
| Keep undetermined (und) | on (automatic hook) / configurable per rule (manual) | Whether tracks tagged und (undetermined language) are preserved. Many releases tag the original-language track as und, so keeping it avoids stripping the one subtitle a re-encode actually needs. |
Per-series override. The automatic trigger can be forced on or off for an individual series from Library → series detail → Cleanup foreign tracks (Inherit / On / Off) — useful for a show where the container carries a rare-language commentary track you want to keep regardless of the global default.
Using Cleanup Operations
Section titled “Using Cleanup Operations”Each operation is an expandable card with:
- Toggle — enable or disable the operation
- Configuration — operation-specific settings (e.g. language list)
- Schedule — manual / daily / weekly / after scan
- Preview — dry run showing up to 20 example files that would be affected, with reason
- Run Now — execute immediately
Dry-Run Preview
Section titled “Dry-Run Preview”Before running any operation, use Preview to see which files would be affected. The preview shows:
- File path
- File size (or track count, for Foreign-Track Removal)
- Reason for deletion (e.g.
lang:ja,replaced by Episode.S01E01.de.ass,no video in folder)
No files are deleted during preview.
Deduplication
Section titled “Deduplication”The Deduplication section below the five operations uses SHA-256 hashing to find identical subtitle files across your library. Run a scan, then choose which copy to keep for each duplicate group.
Subtitle Backups
Section titled “Subtitle Backups”Whenever Sublarr modifies a subtitle in place (HI removal, common-fixes
pipeline, credit-region trim, timing shift, common-fix presets, etc.) it
first writes a .bak.<ext> snapshot of the original next to the active
sub. The dedicated admin page at
Settings → Cleanup → Subtitle Backups is where you see and manage
that fleet of .bak files.
What the page shows
Section titled “What the page shows”For every .bak.srt / .bak.ass on disk:
- Language pill (parsed from the filename —
.de.bak.ass→DE) - Modifier badges (HI / FORCED / SDH / CC) reconstructed from the same filename token grammar the live subs use
- Parent video (with deep-link to the series / movie detail page, if Sublarr can match it)
- Age (relative timestamp — 3d ago, 2 mo ago)
- Orphan flag when no live sibling subtitle exists for that language/modifier combination
Bulk actions
Section titled “Bulk actions”| Action | Effect |
|---|---|
| Purge orphans | Deletes every .bak whose live sibling no longer exists. Useful after a foreign-track cleanup or a Library-wide re-translation pass — the backups become unreachable, so this collects them in one click. |
| Purge aged | Deletes every .bak older than the configured subtitle_bak_retention_days window (default 30 days, set per-instance in Settings → Media Management → Subtitle Trash). |
Per-row actions
Section titled “Per-row actions”| Action | Effect |
|---|---|
| Restore | Atomic three-step swap-rename: live sub → temporary file, .bak → live name, temp file → new .bak. Fully reversible — clicking Restore again brings back the previous active version. |
| Delete | Hard-deletes the .bak only. Live sub is untouched. |
Configuration
Section titled “Configuration”| Setting | Default | Description |
|---|---|---|
| Subtitle Bak Retention (days) | 30 | Maximum age for .bak files before Purge aged is allowed to delete them. 0 means keep forever. |
Cleanup History
Section titled “Cleanup History”Past cleanup runs appear in the History table at the bottom of the page, showing files processed, files deleted, and bytes freed for each run.