Skip to content

Updated backup-and-restore.md to describe the 10.11.0+ built-in backup facility #1510

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Updated backup-and-restore.md to describe the 10.11.0+ built-in backup facility #1510

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a4e7a25
Updated backup-and-restore.md to describe the 10.11.0+ built-in backu…
HammyHavoc Aug 14, 2025
61e32c4
Updated `backup-and-restore.md` based off of feedback
HammyHavoc Aug 14, 2025
7820e72
Updated backup-and-restore.md with a warning
HammyHavoc Aug 14, 2025
7895edb
Updated backup-and-restore.md
HammyHavoc Aug 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 20 additions & 49 deletions docs/general/administration/backup-and-restore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,66 +9,37 @@ This guide documents how to both back up and then restore the data in your Jelly

## Why Backing Up is Important

Backups are important in general for all digital data. There are myriad possible bugs and issues that can arise and cause data loss, especially when you upgrade major releases (for instance, from Jellyfin 10.9.x to Jellyfin 10.10.x).
Backups are important in general for all digital data. There are myriad possible bugs and issues that can arise and cause data loss, especially when you upgrade to a new release of Jellyfin Server.

In addition, Jellyfin does not have a downgrade mechanism. This is very important to understand; once your Jellyfin instance has been started with a new version, any pending migrations are immediately applied, and your Jellyfin data will no longer work with the old version. The **only** way to restore your active instance back to the old version is to restore a backup. Backups are thus critical if you want to test Unstable versions, or before upgrading to the latest version. In fact, when testing Unstable, it is best to back up much more regularly, perhaps using a cron job or similar automatic mechanism, to ensure that your data can be recovered if you hit a major issue.
:::caution

Backups may also come in handy if you hit a bug. For instance, if a bug in the new version causes corruption of some aspect of the Jellyfin data, restoring from a backup means you can quickly restore to good data and apply any fixes to avoid a repeat. Without a backup, you would be completely out of luck in this situation.
Jellyfin does not have a downgrade mechanism. This is very important to understand; once your Jellyfin instance has been started with a new version, any pending migrations are immediately applied, and your Jellyfin data will no longer work with the old version.

Finally, administrative mistakes, normal operation issues (e.g. filling up a disk), or general bit rot can cause corruption or issues that require a backup to be restored. It's always better to have one than not.
The **only** way to restore your active instance back to the old version is to restore a backup. Backups are thus critical if you want to test `Unstable` pre-release versions, or before upgrading to the latest release. In fact, when testing `Unstable`, it is best to back up much more regularly, perhaps using a cron job or similar automatic mechanism, to ensure that your data can be recovered if you hit a major issue.

## Taking a Backup
:::

1. Stop the running Jellyfin server. This is extremely important, as otherwise the database will be locked and might not be recoverable when restoring. Note that this will interrupt any playback.
If a bug in a new version of Jellyfin Server causes corruption of its data, restoring from a backup means you can quickly restore to a working state and potentially apply fixes to avoid a repeat in future. Without a backup, you would likely need to reconfigure Jellyfin from scratch.

* Any platform: Within the Jellyfin Dashboard, click "Shutdown". This should cleanly stop the process on all platforms, but if not, try one of the following.
* Docker: `docker stop jellyfin`
* Debian/Ubuntu packages: `sudo systemctl stop jellyfin` or `sudo service jellyfin stop`
* Windows Installer: Right-click the Tray app, and select "Quit"; or, in Process Manager, find the Jellyfin process and terminate it.
* MacOS Installer (.dmg): In Activity Monitor, find the Jellyfin process and terminate it.
* Portable Installs (regardless of platform): Stop the running `jellyfin` or `jellyfin.exe` program, however it was started.
Other scenarios in which backups make sense include administrative mistakes, normal operation issues (e.g., running out of storage on the disk that your Jellyfin Server database is stored on), general bit rot, or corruption. It is always better to have one than not. It is highly recommended that as soon as you have your Jellyfin Server in a functioning state that you should configure your backup schedule.

2. Copy your data and configuration directories to a destination of your choice. What you name the copies is up to you; personally, I like to use dated and versioned directory names e.g. `jellyfin.2024-05-01_10.8.13`. Where these files are also depends on the platform; generally these follow the [XDG Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/) for platforms that support it. For more information see [the configuration documentation](/docs/general/administration/configuration/#server-paths).
It is strongly recommended to replicate your backups elsewhere so that in the event of major failure, you are able to restore your Jellyfin Server to a previous state.

**NOTE**: These are default locations; if you've changed your data or config paths, use those instead.
## Creating a Backup of Jellyfin Server

* Official Docker: Wherever your `/data` and `/config` volumes are sourced from; this is set in your `docker-compose.yml` or in your `-v` options to `docker run`.
* LinuxServer.io Docker: Data and config are wherever your `/config` volume is sourced from; this is set in your `docker-compose.yml` or in your `-v` options to `docker run`.
* Debian/Ubuntu packages: Data is in `/var/lib/jellyfin` and config is in `/etc/jellyfin`; these are defined in `/etc/default/jellyfin`.
* RPMFusion Fedora/CentOS packages: Data is in `/var/lib/jellyfin` and config is in `/etc/jellyfin`; these are defined in `/etc/sysconfig/jellyfin`.
* Windows Tray/Installer (.exe): Data and config is in `%PROGRAMDATA%\Jellyfin\Server` (`C:\ProgramData\Jellyfin\Server`) or `%LOCALAPPDATA%\Jellyfin` (`C:\Users\<Username>\AppData\Local\Jellyfin`).
* MacOS Installer (.dmg): Data is stored in one of these paths; back up whichever one(s) exist: `~/.config/jellyfin/`, `~/.local/share/jellyfin/`, `~/Library/Application Support/Jellyfin/`.
* Portable Installs:
* Linux: Data is stored in `~/.local/share/jellyfin` and config in `~/.local/share/jellyfin`.
* Windows: Data and config is in `C:\Users\<Username>\AppData\Local\Jellyfin`, using `%LOCALAPPDATA%`.
* MacOS: Data is stored in these paths; back up whichever one(s) exist: `~/.config/jellyfin/`, `~/.local/share/jellyfin/`, `~/Library/Application Support/Jellyfin/`.
As of Jellyfin 10.11.0, a backup facility is included in the core Jellyfin experience.

As an example, on Debian, you can do this with these commands to make a copy of both directories into a single target directory:
You can manually initiate a backup via this facility by following these steps:

```bash
TIMESTAMP=$(date +%Y%m%d%H%M%S)
VERSION=10.9.10
sudo mkdir -p /media/backups/jellyfin.${TIMESTAMP}_${VERSION} # Or change the path wherever in your system makes sense to you
sudo cp -a /var/lib/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/data
sudo cp -a /etc/jellyfin /media/backups/jellyfin.${TIMESTAMP}_${VERSION}/config
```
1. Go to the Jellyfin Server `Dashboard` on the Jellyfin instance you wish to back up.
2. Scroll down to `Advanced` via the left sidebar menu.
3. Click `Backups` in the left sidebar menu.
4. Click the `Create Backup` button.
5. Using the checkboxes, select which aspects of Jellyfin Server you wish to back up. `Database` is always required to be backed up. Other options include `Metadata`, `Subtitles` and `Trickplay`.
6. Click `Create` and wait for your backup to be created.

3. Start up Jellyfin again, either after upgrading or on the current version. You now have a safe copy of your data in the path chosen in step 2.
:::caution

## Restoring a Backup
A backup does not contain your media files, it only contains the files for Jellyfin Server itself.

This process assumes you followed the steps above to take the backup.

1. Stop the running Jellyfin server process.

2. Move your current data and configuration directories out of the way (e.g. by appending `.bak` to them). For example, `sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak` and `sudo mv /etc/jellyfin /etc/jellyfin.bak`.

3. Copy - **do not move or rename** - your backup to the existing name. For example, `sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/data /var/lib/jellyfin` and `sudo cp -a /media/backups/jellyfin.2024-10-27_10.9.11/config /etc/jellyfin`.

4. If required, downgrade Jellyfin to the same version as your backup now.

5. Start up Jellyfin again. It should start cleanly with the old data, assuming versions are correct. If you downgraded this may happen automatically.

## The Future

Long-term, we have plans to provide an official backup and restore plugin bundled with Jellyfin, however this requires the completion of our EFCore rewrite, which is currently slated for our next major release 10.11.0. Once that becomes available, this document will be updated to reflect the process using that plugin.
:::