Backup & Restore

Librariarr includes a full backup and restore system that can run on a schedule or be triggered manually.

Backup Types

Config-Only (Default)

Backs up your configuration, servers, rules, integrations, and settings. Excludes tables that are repopulated by syncing or lifecycle processing:

• Media items
• External IDs
• Media streams
• Sync jobs
• Rule matches
• Lifecycle actions
• Lifecycle exceptions
• Watch history
• Log entries

Use case: Routine backups. After restoring, run a full sync to repopulate media data.

Full Backup

Backs up everything, including all media metadata.

Use case: Migrating to a new instance without wanting to re-sync, or when sync would take a very long time for large libraries.

Enable full backups by checking Include media data when creating a manual backup.

Restoring clears watch history

A restore replaces the whole database, and a config-only backup (the default) contains no watch history — so restoring one leaves every server with none. Your media returns on the next sync; your play history returns when the next watch-history sync refills it, which for a Tracearr-linked server means re-walking the archive. The restore restarts that walk from the newest play, even when the backup was taken while the server’s first import was still running.

In between, every item is present with no record of ever being played. Librariarr handles this rather than letting it arm your rules: restored servers are marked as having no watch history yet, which pauses lifecycle rules that read play activity — Watched By User, Play Count, Last Played and the series aggregates — until a sync re-establishes it. The pause lifts on its own.

Take a full backup (tick Include media data) if you want history to come back with the restore.

Encryption

Backups can be encrypted with a passphrase for security.

• Minimum passphrase length: 8 characters
• Uses strong encryption (AES-256-GCM) with brute-force-resistant key derivation

Set the encryption password in Settings → General → Backup & Restore. While no password is set, the Create Backup panel shows a warning and every backup written (manual or scheduled) is logged as unencrypted in System Logs.

Danger

If you lose the encryption passphrase, encrypted backups cannot be recovered. There is no passphrase reset or recovery mechanism. Store your passphrase securely.

Caution

Backups contain plaintext secrets — Plex tokens, Sonarr/Radarr/Lidarr/Seerr API keys, the OIDC client secret, and the saved backup encryption password itself. Encrypted backups are strongly recommended whenever the file may leave the host or be stored on shared media.

What’s included

Configuration backups capture every column of the configuration tables, including:

• User accounts — usernames, hashed passwords, Plex IDs/tokens, and SSO linkage (ssoSubject, ssoProvider, ssoEnabled)
• App settings — schedules, notifications, theme, and the full SSO configuration (mode, OIDC issuer/client ID/client secret/scopes/username claim, forward-auth header names, master ssoEnabled toggle)
• Media servers, libraries, and integrations (Sonarr, Radarr, Lidarr, Seerr, Tracearr)
• Lifecycle rule sets and the Plex collections they feed, blackout schedules, preroll presets and schedules, saved queries
• TRaSH Guide Sync assignments (which custom formats, quality profiles, sizes and naming Librariarr manages on each Sonarr/Radarr instance)

Backups made before collections and TRaSH assignments were included still restore: rule sets that were assigned to a collection come back without one (reassign it in the rule editor), and TRaSH assignments need to be made again.

API keys are never included — not even their hashes — and restoring a backup deletes every existing API key, so a key you deleted can never be brought back by restoring an older backup. After a restore, create new keys under Settings → Authentication → API Keys for the applications that use the public API.

After restoring, SSO is restored exactly as configured at backup time. If the restored backup has SSO enabled but you cannot reach the IdP from the new environment, use the SSO_DISABLE_OVERRIDE env var to recover access.

Scheduling

Configure automatic backups in Settings → General:

Schedule	Frequency
Manual	No automatic backups
Every 6 hours	4 times per day
Every 12 hours	Twice per day
Daily (default)	Once per day
Weekly	Once per week

Retention

Set how many backups to keep (1–100). After each scheduled backup, the oldest backups beyond the limit are deleted — manual backups count towards the limit, but creating one manually does not prune. Default: 7 backups. A backup that fails part-way is not saved and does not count towards retention, so it never pushes out a good one.

Scheduled backups are always config-only and use the saved encryption password (if set).

Creating a Manual Backup

Note

Creating, downloading and restoring a backup need a sign-in from the last 15 minutes. If it has been longer, Librariarr asks you to confirm it’s you — with your password, or by signing in again with Plex or SSO in a pop-up — and then carries on, without signing you out. A backup holds your Plex token, and a Plex token is enough to sign in to Librariarr on its own, so a browser session alone must not be able to take a copy. Scheduled backups are not affected.

1. Go to Settings → General → Backup & Restore
2. Optionally check Include media data for a full backup
3. Click Create Backup
4. The backup is created and appears in the Available Backups list

Restoring a Backup

From Settings (While Logged In)

1. Go to Settings → General → Available Backups
2. Find the backup you want to restore
3. Click Restore
4. If encrypted, enter the passphrase
5. Confirm the restore — this replaces all current data
6. Monitor progress as each table is restored
7. After completion, you are automatically logged out

From Login Page (No Account)

If no account exists (fresh install or after data loss):

1. Navigate to the login page
2. Backups from /config/backups/ are automatically listed
3. Select a backup to restore
4. Enter passphrase if encrypted
5. After restore, log in with your restored credentials

Note

After restoring a config-only backup, you should trigger a full sync from Settings → Servers to repopulate media metadata.

Restore Process

The restore process:

1. Clears all existing data from the database
2. Restores data table by table (progress is shown in the UI)
3. Brings media restored from an older version’s full backup up to date — for example, the keys that tell a track’s versions on different albums apart — the same repair Librariarr runs at startup
4. On completion, signs out every session on every device and redirects you to the login page

The restore runs in a single transaction. If any step fails — a table that cannot be cleared, a row the database refuses — nothing is changed, and the error names the table where it stopped. For a row that cannot be restored it also names the kind of error and the column or constraint involved, but never the row’s values: the rows hold your Plex token, password hash and other secrets, and the error is shown in the browser and kept in the system log.

Storage

Path	Description
/config/backups/	Default backup directory
BACKUP_DIR env var	Override the default backup directory

Backup files follow the naming pattern: librariarr-backup-{timestamp}.json.gz[.enc]

Each backup file is written readable and writable by its owner only (mode 600), the user the container runs as (PUID), because it holds your integrations’ credentials. To copy backups off the host as another user, read them as root or as that user. Downloads from Settings are sent with Cache-Control: no-store, so no browser or proxy cache keeps a copy.

Managing Backups

From the Available Backups section:

• Download — Save a backup file locally (needs a recent sign-in)
• Restore — Restore this backup (replaces all data; needs a recent sign-in)
• Delete — Remove a backup file

Limitations

• Restoring replaces all data — there is no selective/partial restore
• Encrypted backups require the exact passphrase used at creation time
• The restore process signs out every session on every device, including any that were signed out after the backup was taken — also when the restore runs from the setup screen with no account left — plan accordingly
• Restoring deletes every API key; applications using the public API need new keys
• Full backups can be large for libraries with tens of thousands of items