Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chrisbenincasa/tunarr/llms.txt

Use this file to discover all available pages before exploring further.

Tunarr includes a built-in backup system that creates compressed archives of your configuration, database, and media assets. Backups can run on an automatic schedule or be triggered manually at any time. Backup settings are available under Settings > System > Backup in the Tunarr web UI.

​
What Gets Backed Up

A Tunarr backup archive includes all the files needed to fully restore your installation — channels, programs, artwork, and settings:
ItemDescription
db.dbSQLite database containing channels, programs, and configuration
settings.jsonSystem settings and media source configurations
channel-lineups/Channel lineup data and M3U files
images/Channel logos, artwork, and thumbnails
cache/Cached subtitles, posters, banners, fanart, and watermarks
ms-snapshots/Meilisearch index snapshots (optional, see below)
*.xmlXMLTV output files
The Meilisearch search index (data.ms) is not included in backups by default. Tunarr rebuilds this index automatically on startup, so there is no need to back it up. See Excluding Search Snapshots for details.

​
Backup Configuration

​
Options

OptionDefaultDescription
EnabledtrueEnable or disable scheduled automatic backups
ScheduleDaily at 4:00 AMWhen to run automatic backups
Output Path{data directory}/backups/Where backup files are stored on disk
Archive FormattarArchive format: tar or zip
Gzip CompressionfalseEnable gzip compression (tar archives only)
Max Backups3Number of backup files to retain before deleting the oldest

​
File Naming

Backup files are named using a timestamp: 
tunarr-backup-YYYYMMDD_HHmmss.tar
tunarr-backup-YYYYMMDD_HHmmss.tar.gz  # with gzip compression
tunarr-backup-YYYYMMDD_HHmmss.zip
For example: tunarr-backup-20250118_040000.tar.gz

​
Scheduling Backups

Backups can be scheduled in two ways:

​
Interval-Based Schedule

Run backups at a regular interval, such as every N hours or every N days. For example: “Every 1 day at 4:00 AM.”

​
Cron-Based Schedule

Use a cron expression for more flexible scheduling: 
0 4 * * *    # Daily at 4:00 AM
0 */6 * * *  # Every 6 hours
0 4 * * 0    # Weekly on Sunday at 4:00 AM

​
Manual Backup

​
Via Web UI

Navigate to Settings > System > Backup and click the Backup Now button to trigger an immediate backup.

​
Via API

Trigger a backup using the tasks API: 
curl -X POST "http://localhost:8000/api/tasks/BackupTask/run"
To run the backup in the background (recommended for large installations): 
curl -X POST "http://localhost:8000/api/tasks/BackupTask/run?background=true"

​
Backup Retention

When a new backup is created and the total number of backup files exceeds the maxBackups setting, Tunarr automatically deletes the oldest backup files. This prevents your backup directory from consuming unbounded disk space over time. Adjust the Max Backups setting to match your desired number of recovery points.

​
Restore Process

Tunarr does not currently have a built-in restore feature. Restoration must be performed manually by stopping the server, extracting the backup archive, and copying the files into your data directory.
1

Stop Tunarr

Ensure the Tunarr server is fully stopped before making any changes to the data directory. For Docker users, stop the container:
docker stop tunarr
2

Locate Your Data Directory

Find the Tunarr data directory on your system:
PlatformPath
DockerThe host path you mounted to /config/tunarr
Windows%APPDATA%\tunarr
macOS~/Library/Preferences/tunarr
Linux~/.local/share/tunarr
3

Extract the Backup Archive

Extract the backup to a temporary location:
# For tar archives
tar -xvf tunarr-backup-YYYYMMDD_HHmmss.tar -C /tmp/tunarr-restore/

# For gzipped tar archives
tar -xzvf tunarr-backup-YYYYMMDD_HHmmss.tar.gz -C /tmp/tunarr-restore/

# For zip archives
unzip tunarr-backup-YYYYMMDD_HHmmss.zip -d /tmp/tunarr-restore/
4

Copy Files to the Data Directory

Copy the extracted files into your Tunarr data directory. At minimum, restore the database and settings files. Restore optional directories as needed:
# Required files
cp /tmp/tunarr-restore/db.db /path/to/tunarr/data/
cp /tmp/tunarr-restore/settings.json /path/to/tunarr/data/

# Optional directories (restore as needed)
cp -r /tmp/tunarr-restore/images/ /path/to/tunarr/data/
cp -r /tmp/tunarr-restore/cache/ /path/to/tunarr/data/
cp -r /tmp/tunarr-restore/channel-lineups/ /path/to/tunarr/data/
5

Start Tunarr

Start the Tunarr server. If the backup did not include Meilisearch snapshots, the search index will be rebuilt automatically. Depending on your library size, this may take a few minutes.
docker start tunarr

​
Full Docker Restore Example

# Stop the container
docker stop tunarr

# Extract backup to a temporary location
tar -xzvf tunarr-backup-20250118_040000.tar.gz -C /tmp/tunarr-restore/

# Copy to your mounted volume
cp /tmp/tunarr-restore/db.db /path/to/tunarr/data/
cp /tmp/tunarr-restore/settings.json /path/to/tunarr/data/

# Start the container
docker start tunarr

​
Excluding Search Snapshots

Meilisearch index snapshots (ms-snapshots/) can be large. Since Tunarr automatically rebuilds the search index on startup, there is no need to include snapshots in your backups. To exclude them, set the following environment variable: 
TUNARR_DISABLE_SEARCH_SNAPSHOT_IN_BACKUP=true
When restoring a backup without search snapshots, Tunarr will rebuild the index on its next startup. This may take a few minutes depending on your library size.
There is a known issue in Meilisearch where snapshots do not work correctly on Windows. Windows users should disable Meilisearch snapshots until this is resolved upstream.

​
Excluding data.ms from Proxmox Backup Server

The data.ms directory contains the Meilisearch search index and can be several gigabytes in size. Since Tunarr rebuilds this index automatically on startup, there is no need to include it in Proxmox Backup Server (PBS) jobs. PBS uses .pxarexclude files (similar to .gitignore) to exclude paths from backup jobs. To exclude the data.ms directory, create or edit a .pxarexclude file in your Tunarr data directory: 
# Docker example — adjust to your actual mount path
echo "data.ms/" >> /path/to/tunarr/data/.pxarexclude
The file should contain: 
data.ms/
PBS will skip the data.ms directory in all future backup jobs that include that path. No PBS job reconfiguration is required — the exclusion is applied automatically when PBS encounters the .pxarexclude file.

​
Backup Storage Locations

​
Default Location

Backups are stored in the backups/ subdirectory of your Tunarr data directory:
PlatformDefault Path
Docker/config/tunarr/backups/
Windows%APPDATA%\tunarr\backups\
macOS~/Library/Preferences/tunarr/backups/
Linux~/.local/share/tunarr/backups/

​
Custom Location

You can configure a custom Output Path in the backup settings to store backups on a different drive, a mounted NAS share, or any other accessible path on the host system.

Build docs developers (and LLMs) love

Get started for freeTalk to us