Cleanup

The Cleanup page (Settings → Cleanup) provides five fixed automated operations that remove unnecessary subtitle files and database entries from your library.

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

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.

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

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

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

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 30). 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.

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

Before running any operation, use Preview to see which files would be affected. The preview shows:

File path
File size
Reason for deletion (e.g. lang:ja, replaced by Episode.S01E01.de.ass, no video in folder)

No files are deleted during preview.

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

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

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

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

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

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

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.