Install Jellyfin on Debian or Ubuntu
Install Jellyfin from its official repository, publish it over HTTPS with Caddy, manage accounts and understand the limits of transcoding without a GPU, with updates and backups.
On this page
Your values
Enter them once and the commands in this guide update.
This guide explains how to install Jellyfin, a free media server, from its official repository. The setup wizard is completed through an SSH tunnel, then Caddy publishes the service over HTTPS.
By the end of the guide, Jellyfin answers on https://jellyfin.your-domain.com, its port stays closed from the Internet, each person has their own account, and you know what your server can actually stream without a graphics card.
Order a Server
This guide applies to servers that you administer yourself:
Prerequisites
- An amd64 or arm64 server running Debian 12 or 13, or Ubuntu 22.04 or 24.04
- SSH access with a user that has
sudo - UFW enabled, configured with the guide Configure the UFW firewall without losing SSH access
- Caddy, installed with the guide Caddy as a Reverse Proxy with Automatic HTTPS
- A DNS A record for
jellyfin.your-domain.compointing toYOUR_SERVER_IP, for example with the guide Create an A record - Enough disk space for your media, the metadata and the transcoding cache
The Jellyfin documentation recommends 8 GB of memory and a 100 GB SSD for the system, Jellyfin's files and the transcoding cache, excluding media. For remote access, it advises at least 20 Mbit/s of upload.
Ports Used
| Port | Direction | Purpose | To open |
|---|---|---|---|
| 80/tcp | Inbound | Certificate validation and redirect to HTTPS | Yes |
| 443/tcp | Inbound | HTTPS access to Jellyfin | Yes |
| 443/udp | Inbound | HTTP/3 | Recommended |
| 8096/tcp | Local | Jellyfin HTTP interface | No |
| 8920/tcp | Local | Built-in HTTPS, unused here | No |
| 7359/udp | Local | Local network discovery, useless on a remote server | No |
Step 1: Check the Firewall
sudo ufw status verbose
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udpThe first command must show Status: active and an incoming policy of deny. If it does not, stop and enable UFW. Do not add any rule for 8096.
Step 2: Add the Official Repository
Install the required tools and the repository's signing key:
sudo apt update
sudo apt install -y curl gnupg
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | sudo gpg --dearmor --yes -o /etc/apt/keyrings/jellyfin.gpgOn Ubuntu only, enable the Universe component, which provides FFmpeg dependencies:
sudo apt install -y software-properties-common
sudo add-apt-repository -y universeThen declare the repository:
export VERSION_OS="$(awk -F'=' '/^ID=/{ print $NF }' /etc/os-release)"
export VERSION_CODENAME="$(awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release)"
export DPKG_ARCHITECTURE="$(dpkg --print-architecture)"
cat <<EOF | sudo tee /etc/apt/sources.list.d/jellyfin.sources
Types: deb
URIs: https://repo.jellyfin.org/${VERSION_OS}
Suites: ${VERSION_CODENAME}
Components: main
Architectures: ${DPKG_ARCHITECTURE}
Signed-By: /etc/apt/keyrings/jellyfin.gpg
EOF
sudo apt updateStep 3: Install a Specific Version
Jellyfin asks that you not skip major versions when updating. This guide therefore installs a chosen version, then holds it so that an apt upgrade does not change it without you.
Packages carry a suffix specific to your system, for example deb13 or ubu2404:
. /etc/os-release
case "$ID" in
debian) SUFFIX="deb${VERSION_ID}" ;;
ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
echo "$SUFFIX"
apt-cache madison jellyfin-server | head -n 5Install the version, then hold it:
sudo apt install -y "jellyfin=12.4+${SUFFIX}" "jellyfin-server=12.4+${SUFFIX}" "jellyfin-web=12.4+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-webThe package also installs jellyfin-ffmpeg, the version of FFmpeg suited to Jellyfin. Check the service:
systemctl status jellyfin --no-pager
curl -fsS http://127.0.0.1:8096/healthThe last command must return Healthy. From your computer, the port must remain closed:
nc -vz -w 5 YOUR_SERVER_IP 8096This command must fail. If nc is not available, open http://YOUR_SERVER_IP:8096 in a browser: the page must not load. If the connection succeeds, stop Jellyfin with sudo systemctl stop jellyfin and fix the firewall before continuing.
Step 4: Prepare the Media
Create a folder that the Jellyfin service can read and that your user can write to:
sudo mkdir -p /srv/media/movies /srv/media/shows /srv/media/music
sudo chown -R YOUR_USER:jellyfin /srv/media
sudo chmod -R u=rwX,g=rX,o= /srv/media
sudo find /srv/media -type d -exec chmod g+s {} +From your computer, send your files with rsync:
rsync -avh --progress ./my-videos/ YOUR_USER@YOUR_SERVER_IP:/srv/media/movies/Step 5: Finish the Wizard Through an SSH Tunnel
From your computer, open a tunnel and leave this session open:
ssh -L 8096:127.0.0.1:8096 YOUR_USER@YOUR_SERVER_IPOpen http://localhost:8096, then follow the wizard:
- Choose the language.
- Create the administrator account with a long, unique password.
- Add your libraries by selecting the folders under
/srv/media, or skip this step. - Choose the metadata language.
- Leave Allow remote connections to this server checked: behind the proxy, your visitors will be seen as remote.
Step 6: Restrict Jellyfin to the Loopback Interface
Sign in, then open Dashboard > Networking and fill in:
| Field | Value | Purpose |
|---|---|---|
| Bind to local network address | 127.0.0.1 |
Jellyfin only listens on the server |
| Known proxies | 127.0.0.1 |
Jellyfin accepts Caddy's X-Forwarded-* headers |
Save, then restart the service and check the listening address:
sudo systemctl restart jellyfin
sudo ss -ltnp | grep 8096
sudo grep -A1 -E '<(KnownProxies|LocalNetworkAddresses)>' /etc/jellyfin/network.xmlThe port must appear on 127.0.0.1:8096 only. The SSH tunnel keeps working.
Without a known proxy, Jellyfin ignores the address forwarded by Caddy and treats all visitors as local: remote access restrictions then no longer apply.
Step 7: Publish Jellyfin over HTTPS
Add this site to /etc/caddy/Caddyfile, or to a file in /etc/caddy/sites/:
jellyfin.your-domain.com {
reverse_proxy 127.0.0.1:8096
}Caddy forwards the WebSockets used by Jellyfin without any special setting. Do not enable a full access log on this site: some Jellyfin URLs may contain an api_key parameter.
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyCheck the Result
curl -I http://jellyfin.your-domain.com
curl -fsS https://jellyfin.your-domain.com/healthThe first command must return a 308 redirect to HTTPS, the second Healthy. Then sign in at https://jellyfin.your-domain.com, play a video and check that it starts. In the Jellyfin apps, enter this same address as the server.
Manage Accounts
In Dashboard > Users, create one account per person with Add User. Use an account without administrator rights yourself to watch your content.
For each account, check these settings:
- limit access to the relevant libraries only;
- enable Hide this user from login screens so as not to expose the list of accounts;
- fill in Failed login tries before user is locked out, for example with
5. This lockout is not active by default, and the account is disabled once the threshold is reached; - uncheck Allow video playback that requires transcoding if the server cannot keep up.
Jellyfin does not offer native two-factor authentication: enforce long, unique passwords. To reactivate a locked account, an administrator unchecks Disable this user in its profile. So keep a second, backup administrator account.
Understand the Limits Without a GPU
Jellyfin can play a file in four ways, from the lightest to the most costly:
| Mode | Processing | Server load |
|---|---|---|
| Direct Play | File sent as is | Almost none |
| Remux | Container changed, streams kept | Low |
| Direct Stream | Audio converted, video kept | Low to moderate |
| Transcode | Video re-encoded on the fly | Very high |
To stay in good conditions:
- Favor formats your devices play natively, by consulting the codec compatibility table.
- Check the playback mode in the dashboard during a stream: it shows whether a video is being transcoded and why.
- Block video transcoding for the relevant accounts. An incompatible file may then refuse to play, but it will no longer saturate the server.
- Limit the threads in Dashboard > Playback > Transcoding, with Transcoding thread count. The server stays responsive, but playback may stutter.
- Avoid a bitrate limit that is too low in Playback > Streaming. A video whose bitrate exceeds Internet streaming bitrate limit (Mbps) is transcoded to fit it.
- Watch the disk: temporary files go to
/var/cache/jellyfin/transcodes. Plan for roughly the size of your largest file, multiplied by the number of simultaneous streams.
If your server has a compatible GPU, follow the Hardware acceleration documentation. Also take into account the bandwidth and traffic volume of your plan: each stream consumes a bitrate close to that of the file.
Update Jellyfin
Jellyfin cannot roll back: at first startup, migrations modify the data. Read the release notes and back up before any update.
Check the installed version and the available ones:
jellyfin --version
sudo apt update
apt-cache madison jellyfin-serverAfter the backup, replace 12.4 with the target version:
. /etc/os-release
case "$ID" in
debian) SUFFIX="deb${VERSION_ID}" ;;
ubuntu) SUFFIX="ubu$(echo "$VERSION_ID" | tr -d .)" ;;
esac
TARGET=12.4
sudo apt-mark unhold jellyfin jellyfin-server jellyfin-web
sudo apt install -y "jellyfin=${TARGET}+${SUFFIX}" "jellyfin-server=${TARGET}+${SUFFIX}" "jellyfin-web=${TARGET}+${SUFFIX}"
sudo apt-mark hold jellyfin jellyfin-server jellyfin-web
sudo journalctl -u jellyfin --no-pager -n 50Back Up and Restore
Since Jellyfin 10.11, Dashboard > Backups > Create Backup produces an archive while the server is running. It is stored in /var/lib/jellyfin/data/backups, with at least 5 GB of free space required, and is restored from the same page. Copy these archives off the server.
The manual method is suited to before an update, because it keeps the whole configuration and is done with the service stopped:
sudo systemctl stop jellyfin
sudo mkdir -p /var/backups/jellyfin
sudo tar -czpf "/var/backups/jellyfin/jellyfin-$(date +%F)-$(dpkg-query -W -f='${Version}' jellyfin-server).tar.gz" /etc/jellyfin /var/lib/jellyfin
sudo systemctl start jellyfin
sudo chmod -R go-rwx /var/backups/jellyfinThe file name contains the version: restore it with that same version. Check that the archive contains the database:
sudo sh -c 'tar -tzf "$(ls -1t /var/backups/jellyfin/*.tar.gz | head -n 1)" | grep "jellyfin.db$"'To restore, replace the archive name:
ARCHIVE=/var/backups/jellyfin/jellyfin-2026-11-18-12.4+deb13.tar.gz
sudo systemctl stop jellyfin
sudo mv /var/lib/jellyfin /var/lib/jellyfin.bak
sudo mv /etc/jellyfin /etc/jellyfin.bak
sudo tar -xzpf "$ARCHIVE" -C /
sudo systemctl start jellyfinThese backups do not contain your media. Keep /srv/media separately, for example with rsync to another location.
Troubleshooting
Unable to locate package jellyfin or Repository Error
Check the repository file and the name of your release:
cat /etc/apt/sources.list.d/jellyfin.sources
sudo apt updateSuites must be bookworm, trixie, jammy or noble. URIs must end with debian or ubuntu.
Version '12.4+...' for 'jellyfin' was not found
The SUFFIX variable is empty or the version does not exist for your system. Run echo "$SUFFIX", then compare with apt-cache madison jellyfin-server.
Unmet jellyfin-ffmpeg Dependencies on Ubuntu
The Universe component is not enabled. Repeat the add-apt-repository command from step 2, then sudo apt update.
address already in use
Another program is using port 8096:
sudo ss -ltnp | grep 8096
sudo journalctl -u jellyfin --no-pager -n 50502 Error in the Browser
Jellyfin is stopped or is not listening on 127.0.0.1:8096. Check with systemctl status jellyfin --no-pager and curl -fsS http://127.0.0.1:8096/health. At the first startup after an update, migrations can take time.
Interface Unreachable After a Network Change
Fix the configuration directly, with the service stopped:
sudo systemctl stop jellyfin
sudo nano /etc/jellyfin/network.xml
sudo systemctl start jellyfinLocalNetworkAddresses and KnownProxies must each contain <string>127.0.0.1</string>.
Remote Connections Are Refused
Check that Allow remote connections to this server is checked in Dashboard > Networking, and that the user's profile allows it too.
A Library Stays Empty
The service probably does not have access to the files:
sudo -u jellyfin ls -la /srv/media/moviesIn case of Permission denied, repeat the commands from step 4, then rescan the library.
Playback Stutters or the CPU Stays at 100%
The video is probably being transcoded. Check the playback mode in the dashboard, then apply the advice in the section on limits without a GPU. Conversion errors are found in the files in /var/log/jellyfin:
sudo ls -lt /var/log/jellyfin | headNo space left on device During Playback
The transcoding cache has filled the disk:
df -h /var/cache/jellyfin
sudo du -sh /var/cache/jellyfin/transcodes