emby.wiki · DOCUMENTATION

Setting Up an Emby Home Service

A complete home Emby guide covering device selection, installation, storage, libraries, hardware transcoding, remote access, backups and troubleshooting.

Updated 1 Oct 2026English

Build a home media service from an always-on PC, mini PC, Mac or NAS, and watch it on your TV, phone, tablet and computer. This guide covers hardware, installation, storage mounts, libraries, hardware transcoding, remote access, startup, backups and troubleshooting.

Make playback work on your home LAN before configuring remote access. The platform installation sections are alternatives: choose one route. Do not install the native and Docker versions simultaneously on the same device. This guide uses official Emby Server packages and images, not modified installers.

1. Before you start: choose a deployment#

Emby Server manages media, users and playback sessions; client apps play the content. Media can be stored on the Emby host or on a separate NAS accessed through SMB or NFS.

Existing device	Installation route	Suitable use	Main checks
Windows PC / mini PC	Native Windows server	First deployment, spare computer	Sleep, startup, service account access to NAS
Mac mini	Native macOS server	Always-on Mac with external disks	Login startup versus system startup
Debian / Ubuntu mini PC	Native Linux server	Standard managed system service	Media and GPU permissions
Linux with Docker	Official image and Compose	Portable, persistent configuration	UID/GID, volumes, container paths
Synology / QNAP	Package or container	All-in-one NAS	CPU architecture and shared-folder ACLs
TrueNAS / Unraid	Apps / container	Existing storage platform	Datasets, persistence, actual host ports
Raspberry Pi	ARM package or official image	A few users, mostly Direct Play	Do not assume reliable 4K live transcoding
NAS and separate mini PC	NAS storage, Emby on mini PC	Separate storage from compute	Wired LAN, mounts, startup order

1.1 Three practical home layouts#

Simple: Windows and a local drive. Install Emby on Windows and keep media in D:\Media. Clients connect using the server's LAN IP. Test existing hardware before purchasing more equipment.

Separate storage and compute: Linux mini PC and NAS. The NAS stores media; the mini PC handles libraries, users and transcoding. An x86 device with an Intel integrated GPU is an option when transcoding is needed, but capacity depends on codecs, HDR, subtitles and concurrent sessions. A CPU model alone cannot guarantee a session count.

All-in-one NAS. Run a native package or container on the NAS. If its video hardware is unsuitable, prioritize clients that can Direct Play your files.

1.2 Overall architecture#

flowchart TD
  R["Home router / wired LAN"] --- S["Emby host"]
  R --- N["NAS"]
  N -->|"SMB / NFS media reads"| S
  D["Local / external disks"] --> S
  S --> C["TV / computer / phone"]
  S --> V["Private VPN"]
  V --> O["Remote devices"]

1.3 Example values and command conventions#

Setting	Example	Replace with
Emby host LAN IP	192.168.1.20	Your reserved server address
NAS LAN IP	192.168.1.10	Your NAS address
SMB share	Media	Actual shared-folder name
Linux media path	/mnt/media	Your disk or NAS mount point
Docker project directory	/srv/emby	Your Compose and configuration location
Container media path	/media	A stable internal media path

Run Linux commands in order with a sudo-capable account; root can omit sudo. Run PowerShell on Windows. Replace addresses, account IDs and paths before executing commands. localhost always means the device making the request: localhost on your phone is not your server.

2. Prepare hardware, disks and networking#

2.1 Hardware requirements follow playback behavior#

Direct Play mainly needs storage reads and network throughput. Video transcoding needs CPU resources or a supported GPU. Start with an existing PC, Mac mini or mini PC where possible. Use an SSD for the operating system, Emby database and metadata, and large HDDs for media. Give transcoding its own temporary directory with sufficient capacity.

For an always-on device, check Ethernet, cooling, power, USB disk reliability and system maintenance. RAM usage grows with library size, scanning, plugins and concurrency; one memory figure is not a universal minimum. Use a Windows version that still receives appropriate security maintenance.

2.2 Local disks and external enclosures#

Confirm disks are mounted and their paths remain stable across reboots. Assign a stable drive letter on Windows; macOS often uses /Volumes/Media; Linux can mount by UUID to avoid enumeration changes. Check external enclosure power, disconnects and sleep/wake behavior.

RAID can improve availability in certain disk failures but does not replace backups. Prioritize family photos, home videos and configuration. Deletion, corruption and ransomware can affect an entire array. Sequential read speed is only one factor: scanning also depends on latency, many small files and disk spin-up.

2.3 Stable LAN addresses and Ethernet#

Reserve an address such as 192.168.1.20 for the Emby host in the router's DHCP settings; reserve the NAS address too. Wire the server, NAS and router where practical. A Wi-Fi link rate is not usable application throughput, and high-bitrate 4K files have peaks.

Public IPv4, CGNAT, IPv6 and symmetric upload/download speeds depend on the ISP and plan. Remote playback uses your home's upload; local playback normally stays on the LAN. Measure the actual connection instead of assuming upload is always 10% of download.

3. Native Windows installation#

3.1 Install and open the server#

Open the official Emby download page, choose Windows Server and download a stable release.
Install and start Emby Server. On the server itself open http://127.0.0.1:8096.
Complete section 9, then try http://192.168.1.20:8096 from another LAN device.
Prevent automatic system sleep. Turning off the display does not require putting the server to sleep.

Check the listener and local HTTP response in PowerShell:

Get-NetTCPConnection -LocalPort 8096 -State Listen
Invoke-WebRequest -Uri http://127.0.0.1:8096 -UseBasicParsing
Test-NetConnection 192.168.1.20 -Port 8096

The final command can also run on another Windows computer. If local access works but LAN access fails, check the IP, Windows network profile, firewall and guest Wi-Fi isolation.

3.2 Windows Firewall#

Use the Private profile only on a trusted home network. If the installer has not supplied a suitable rule, an administrator PowerShell session can add a LAN-only rule:

New-NetFirewallRule -DisplayName "Emby HTTP - Home LAN" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8096 -Profile Private -RemoteAddress LocalSubnet

This does not include Tailscale addresses. Configure additional rules for the actual Tailscale interface, profile and allowed sources when needed. Do not disable the entire firewall to fix connectivity.

Login startup is sufficient for a computer that stays signed in. For unattended operation, follow the official Windows Service guide using NSSM.

Install and initialize Emby normally; record the EmbyServer.exe location and actual data directory.
Exit the existing process to avoid port conflicts and simultaneous database writes.
Obtain NSSM from its official source and keep nssm.exe in a permanent directory.
In an elevated terminal run nssm install. Set Application to EmbyServer.exe, Startup directory to its containing directory, and Arguments to -service.
Choose the actual service account. It needs media reads and writes to configuration and transcoding directories. Configure exit actions as the official guide describes so shutting down Emby does not immediately restart it.
Start the service and confirm it uses the original data. If a fresh setup wizard appears, stop and check the account and data path before creating another configuration.

A Windows Service cannot use a normal user's session-mapped drive such as Z:. Use a UNC path such as \192.168.1.10\Media and give the service identity appropriate share access and credentials. Service mode does not perform normal automatic application updates: back up, stop the service, install the update manually, then restart and verify.

4. Native macOS / Mac mini installation#

4.1 Install in Applications#

Download the stable Intel or Apple Silicon build from the official macOS page.
Move EmbyServer into /Applications and start it there, rather than running permanently from Downloads.
Open http://localhost:8096 on the Mac.
Select the real external-volume path, such as /Volumes/Media/Movies.
If reads fail, check mounting, the running user and macOS privacy prompts; grant only the access needed.

Terminal checks:

lsof -nP -iTCP:8096 -sTCP:LISTEN
curl -I http://127.0.0.1:8096
ls -ld /Volumes/Media

Adding Emby Server under System Settings → General → Login Items normally starts it after user login. Configure the Mac to remain awake on power, and verify playback while the screen is locked.

Running before login requires a deliberately configured launchd service. A LaunchAgent depends on a user session; a LaunchDaemon runs at system level. The service user, executable entry point, data path and external-volume permissions must match the installed version. Another machine's plist is not a universal recipe.

This guide uses the verifiable Login Items route rather than supplying an untested generic LaunchDaemon command. If unattended cold boot is essential, consider native Linux systemd or NAS service management. FileVault can also require someone to unlock the system disk after a cold boot. Disabling encryption or enabling automatic login is not the default solution.

5. Native Debian / Ubuntu installation#

5.1 Identify the system and architecture#

cat /etc/os-release
uname -m
ip -br addr

x86_64 generally corresponds to amd64 and aarch64 to arm64; verify 32-bit ARM support separately. The commands below use Emby's stable APT repository on supported Debian / Ubuntu systems.

5.2 Add the official repository and install#

sudo apt update
sudo apt install -y curl ca-certificates
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://pkg.emby.media/keys/emby-public.gpg -o /etc/apt/keyrings/emby-public.gpg
sudo chmod 0644 /etc/apt/keyrings/emby-public.gpg
sudo curl -fsSL https://pkg.emby.media/apt/emby.sources -o /etc/apt/sources.list.d/emby.sources
sudo apt update
apt-cache policy emby-server
sudo apt install -y emby-server
sudo systemctl enable --now emby-server

Before installing, apt-cache policy should show the stable package source at pkg.emby.media. If beta or other Emby repositories already exist, review them first rather than mixing channels. See the official APT instructions.

5.3 Verify operation#

systemctl status emby-server --no-pager
sudo ss -lntp | grep ':8096'
curl -I http://127.0.0.1:8096
journalctl -u emby-server -n 80 --no-pager

When the service is running, listening and responding locally, open http://192.168.1.20:8096 from a LAN client. If UFW is already enabled, allow only the actual home subnet:

sudo ufw allow from 192.168.1.0/24 to any port 8096 proto tcp

This is not a complete UFW setup procedure. Preserve SSH access before enabling or changing firewall rules on a remotely managed host.

5.4 Media permissions: inspect before changing#

Native packages normally run as emby. Verify the actual identity and every parent directory:

id emby
systemctl show emby-server -p User -p Group
namei -l /mnt/media/Movies
sudo -u emby ls -lah /mnt/media/Movies

Directories need traversal permissions and files need read permissions. For a local media directory you own and manage, a media group is one option:

sudo groupadd -f media
sudo usermod -aG media emby
sudo chgrp -R media /mnt/media
sudo find /mnt/media -type d -exec chmod g+rx {} +
sudo find /mnt/media -type f -exec chmod g+r {} +
sudo systemctl restart emby-server
sudo -u emby ls -lah /mnt/media/Movies

Apply recursive changes only to that managed local media tree, not the whole /mnt, system directories or NAS shares with their own ACLs. These commands preserve owner permissions and do not make every file executable. Add group write access only to specific directories where NFO or image writes are needed. Configuration, database and transcoding directories must be writable; media can remain read-only. Do not default to chmod -R 777 or running the server as root.

6. Docker Compose deployment#

6.1 Install Docker and Compose#

This section targets Linux Docker Engine. Do not assume Docker Desktop has identical GPU or host-network behavior. If Docker is already installed, check docker version and docker compose version before changing installation sources.

A fresh Debian 12 / 13 host can use the official Debian instructions. Ubuntu must use the Ubuntu instructions, not Debian repository URLs. The following block is for a fresh Debian host only:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world
sudo docker compose version

If docker.io, containerd or another container platform is already present, review conflicts using the official guide before removing anything. This guide uses sudo for Docker and does not require adding a normal user to the highly privileged docker group.

6.2 Persistent directories and a dedicated identity#

Create a dedicated non-root account and record its numeric UID/GID; do not assume they are 1000:

sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin emby-docker
id emby-docker
sudo install -d -m 0755 /srv/emby
sudo install -d -o emby-docker -g emby-docker -m 0750 /srv/emby/config /srv/emby/transcode
ls -lah /mnt/media

Skip useradd if the account already exists. The media path must contain real files and be readable by the configured identity. Complete NAS mounting in section 8 first. An empty /mnt/media directory will produce an empty container media directory.

Create /srv/emby/.env and replace the placeholders:

EMBY_UID=REPLACE_WITH_ACTUAL_UID
EMBY_GID=REPLACE_WITH_ACTUAL_GID
EMBY_EXTRA_GIDS=REPLACE_WITH_ACTUAL_GID

For the basic setup, EMBY_EXTRA_GIDS can equal EMBY_GID. Add actual media and GPU group numbers as a comma-separated list when required. Values such as 995,44,109 are examples, not portable defaults.

6.3 Minimal working Compose, without a GPU dependency#

Create /srv/emby/compose.yaml:

services:
  emby:
    image: emby/embyserver:latest
    container_name: emby
    environment:
      UID: "${EMBY_UID}"
      GID: "${EMBY_GID}"
      GIDLIST: "${EMBY_EXTRA_GIDS}"
    ports:
      - "192.168.1.20:8096:8096"
    volumes:
      - /srv/emby/config:/config
      - /srv/emby/transcode:/transcode
      - /mnt/media:/media:ro
    restart: unless-stopped

Replace the bind address with the host's real reserved LAN IP. If that address does not exist, startup fails. This LAN-only binding will not automatically serve the host's Tailscale IP: add a separate binding to that actual address or use section 12's subnet-router route. A bare 8096

mapping normally binds multiple interfaces, so check external reachability before using it.

The official image uses UID, GID and GIDLIST; do not substitute another image's PUID/PGID variables. /config persists configuration. /media

prevents writes to media-side NFO/images. Add /media/Movies inside Emby, not the host path /mnt/media/Movies. See the official image documentation.

6.4 Start and verify#

cd /srv/emby
sudo docker compose config
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail 100 emby
sudo docker exec emby ls -lah /media

Open http://192.168.1.20:8096 from a LAN client and set the transcoding temporary directory to /transcode. Do not use /config or /media as a temporary directory.

Docker-published ports can bypass ordinary UFW inbound rules. Combine deliberate address binding, router controls and Docker-compatible firewall rules. A UFW rule alone does not prove a container port is inaccessible externally.

6.5 Host versus bridge networking#

Mode	Configuration	Behavior
Bridge	ports mappings	Explicit bind addresses; discovery and DLNA may need more setup
Host	network_mode: host	Shares the Linux host network; LAN discovery and DLNA are often easier

For host mode add network_mode: host under the service and remove the whole ports section. Do not use both. Review Emby listeners, host firewall and external routing. An occupied 8096 also conflicts in host mode. DLNA depends on the installed version, plugins and client, not networking alone.

6.6 Update and prepare for rollback#

Back up as described in section 14, and record the image ID / server version first. latest is a floating tag; a verified version tag or digest gives reproducibility.

cd /srv/emby
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail 80 emby

Updates pull an image and recreate the container. Do not delete config as an update fix. After a database migration, changing back to an older image may be insufficient; retain the matching pre-update configuration backup.

7. NAS and Raspberry Pi installation routes#

7.1 Synology DSM native package#

Identify your model, DSM version and CPU architecture; download the matching SPK from the official Synology page.
Use Package Center → Manual Install, select the SPK, install and start the server.
Check the package's internal system user in DSM shared-folder permissions. Grant media read access, adding write access only if NFO/images will be saved alongside media. Names and menus depend on the package.
From another device open http://NAS-LAN-IP:8096 and select the real media folder path.
If DSM Firewall is enabled, allow required traffic only from trusted LAN or private-network sources.

Installing a package does not automatically grant access to every share. Do not give Everyone full read/write access by default.

7.2 Synology Container Manager#

Supported models can use section 6's Compose with DSM paths:

Purpose	Example host path	Container path
Configuration	/volume1/docker/emby/config	/config
Temporary transcoding	/volume1/docker/emby/transcode	/transcode
Media	/volume1/media	/media

Create directories and set ACLs before deploying the project. On an Intel GPU model, check /dev/dri and add device mappings only when nodes really exist. Get UID/GID from the DSM account; Debian values are not portable. privileged and UID=0 are not default requirements.

7.3 QNAP#

Download the architecture-matched QPKG from the official QNAP page, install through App Center and open the NAS IP with the actual service port. Give the application/container identity the needed share permissions.

Native QNAP package caveat: Current Emby instructions require allowing installation and execution of applications without a digital signature, and note that switching this off can cause the application to be stopped by QNAP. This reduces App Center's default protection. Understand the change and use official sources only. If it is unacceptable, evaluate a supported Container Station deployment.

A container still needs the official image, persistent config, real UID/GID and deliberate media access. Do not forward the NAS administration interface to the internet.

7.4 TrueNAS SCALE / Community Edition#

Current container-based Apps differ from CORE jails and older SCALE application systems. Check the Emby App catalog for current requirements rather than applying one UI procedure to all versions.

Configure the Apps pool and find Emby under Discover Apps.
Prepare a separate configuration dataset such as tank/apps/emby/config and a media dataset such as tank/media. Do not create your own datasets under internally managed ix-apps / ix-applications.
Set persistent Host Path storage and media mappings, keeping /media as a stable container path where possible. Record the actual run-as UID/GID. Configuration needs writes; media needs reads and parent traversal.
Select the actual GPU in resource configuration if transcoding is required, and verify drivers and device availability.
Open the deployed app through Web Portal. Its host port may be different from 8096, for example 9096; use the form and portal's actual value.

For Permission denied, inspect ACLs along the whole dataset path, the running identity and mounts. Do not recursively overwrite permissions on the entire pool. See the TrueNAS deployment guide.

7.5 Unraid#

Find an Emby template in Apps and check the maintainer and image repository. Use official emby/embyserver. Map /mnt/user/appdata/emby to /config and /mnt/user/media to /media, with correct identity and ports.

Keep appdata and media in separate persistent locations. Intel acceleration uses the real /dev/dri nodes; NVIDIA first needs platform-supported drivers and a container GPU runtime. Template defaults are not evidence that paths and permissions fit your machine. Check logs, WebUI and media inside the container.

7.6 Raspberry Pi#

Check uname -m; a 64-bit ARM OS normally reports aarch64. Choose a supported ARM package or the official multi-platform container image. Follow the native or Docker route without copying x86-specific GPU settings.

Use reliable storage for the database, put media on USB disks or NAS, and check power, cooling and Ethernet. A Pi is better suited to a few users, music, photos and videos clients can play directly. Hardware transcoding depends on the model, kernel, image and Emby support. The existence of /dev/video* does not prove Emby has usable hardware encoding. Do not assume multi-user 4K HEVC/HDR live transcoding.

8. Mount NAS storage with SMB or NFS#

Use one protocol for a given mount point. Create a dedicated NAS media-reader account or restricted NFS export rather than using the NAS administrator. These examples run on a Debian / Ubuntu Emby host.

8.1 SMB credentials and a read-only mount#

sudo apt install -y cifs-utils
sudo mkdir -p /mnt/media
sudo install -m 0600 /dev/null /root/.emby-smbcredentials
sudo nano /root/.emby-smbcredentials

Enter real credentials in this protected file, not in public Compose files, screenshots or repositories:

username=NAS_MEDIA_USER
password=NAS_MEDIA_PASSWORD

Get the actual UID/GID with id emby for native installation or id emby-docker for Docker. uid=123 and gid=123 below are placeholders: replace them before running:

sudo mount -t cifs //192.168.1.10/Media /mnt/media -o credentials=/root/.emby-smbcredentials,vers=3.0,ro,uid=123,gid=123,file_mode=0640,dir_mode=0750
findmnt /mnt/media
ls -lah /mnt/media

Verify the NAS supports the chosen SMB version. Do not enable SMB1 as a workaround. Client uid/gid settings do not bypass NAS share ACLs.

After a successful test, back up /etc/fstab and add the following line with the real numeric IDs:

//192.168.1.10/Media /mnt/media cifs credentials=/root/.emby-smbcredentials,vers=3.0,ro,uid=123,gid=123,file_mode=0640,dir_mode=0750,_netdev,nofail,x-systemd.automount 0 0

If the test mount remains active, stop Emby and unmount it in a maintenance window before reloading fstab. Do not unmount media during playback:

sudo systemctl daemon-reload
sudo mount -a
ls /mnt/media
findmnt -T /mnt/media

For metadata writes, adjust both NAS permissions and mount settings; merely removing ro is insufficient. Do not apply local-disk chmod instructions blindly to CIFS mounts.

8.2 NFS access and identity mapping#

Enable NFS on the NAS and restrict allowed clients to the Emby host. Export paths are vendor-specific and may not be /volume1/media:

sudo apt install -y nfs-common
sudo mkdir -p /mnt/media
showmount -e 192.168.1.10
sudo mount -t nfs -o ro 192.168.1.10:/volume1/media /mnt/media
findmnt /mnt/media
ls -lah /mnt/media

showmount may not list exports on an NFSv4-only server. If it fails, check the actual NFS path in the NAS UI. Once mounting succeeds, add the verified path to /etc/fstab:

192.168.1.10:/volume1/media /mnt/media nfs ro,_netdev,nofail,x-systemd.automount 0 0

Review export restrictions, UID/GID mapping and ACLs. Client chmod alone cannot fix server-side permissions. Do not default to disabling root squash or allowing internet-wide clients.

8.3 When the NAS starts after Emby#

_netdev marks network storage, nofail lets the host boot despite mount failure, and automount can trigger mounting on access. None guarantees the NAS is online or that Emby waits for a successful mount.

For native systemd deployment, add a startup dependency:

sudo systemctl edit emby-server

Enter:

[Unit]
Wants=network-online.target
After=network-online.target
RequiresMountsFor=/mnt/media

Save, then:

sudo systemctl daemon-reload
sudo systemctl restart emby-server
systemctl status emby-server --no-pager
findmnt -T /mnt/media/Movies

This assumes /mnt/media is correctly configured in fstab. It constrains startup but does not replace monitoring a failed mount. Pause scans during prolonged NAS outages; restore mounting before resuming service.

Docker restart policies do not check NAS readiness. Validate the mount before starting the container or implement separate service management with mount dependencies and prechecks. Adding dependencies to the entire docker.service would affect other containers and is not the default fix.

8.4 Cloud drives, WebDAV, rclone and STRM#

Treat these as advanced extensions after local storage works. rclone VFS cache consumes local space; scanning and seeking depend on latency, remote API limits and cache hits. STRM stores an address, not the movie; the client or server must still reach the actual media endpoint.

302 redirects, expiring signed URLs and cloud-provider playback rules vary. Do not assume permanent support across clients or providers. Set cache limits, handle errors, and avoid keeping important family media and configuration with only one remote provider.

9. Initial setup, users and libraries#

9.1 Setup wizard#

Open the server on a trusted LAN; choose language and server name.
Create an administrator with a strong password before allowing public access.
Add a small test library. Verify content type, folder, metadata language and region.
For LAN-only use, disable external remote access and automatic port mapping. For private VPN use, configure remote-access settings and access controls for the actual route. Enabling a checkbox does not secure an installation by itself.
Finish, scan and actually play one file.

Settings names vary by release. Emby Connect assists server sign-in but does not solve CGNAT, routes, ports or insufficient bandwidth.

9.2 Separate administration from viewing#

Use the administrator for maintenance and normal users on TVs and family devices. Limit library access and disable media deletion, server administration and other unnecessary management capabilities. Apply appropriate ratings and restrictions for children.

Read-only filesystem/container mounts add another barrier against media changes but do not replace application user permissions. Do not make everyone an administrator to test playback.

9.3 Folder planning and naming#

Create separate libraries for movies, TV, music and photos:

Content	Container path	Native Linux example
Movies	/media/Movies	/mnt/media/Movies
TV	/media/TV	/mnt/media/TV
Music	/media/Music	/mnt/media/Music
Family photos	/media/Photos	/mnt/media/Photos

For movies, use Title (Year) folders and matching filenames, for example Movies/Avatar (2009)/Avatar (2009).mkv. For incorrect matches, identify the item using its correct database ID, or use a supported identifier such as [tmdbid=ACTUAL_ID] in the name.

For TV, use a show folder, season folder and SxxExx episode numbers, such as TV/Example Show (2020)/Season 01/Example Show - S01E01.mkv. Check movie naming and TV naming for specials, multiple episodes and other cases rather than mixing every season into one directory.

9.4 tinyMediaManager and NFO#

tinyMediaManager can identify titles, fetch images, create NFO and organize names. Back up first and test renaming on a small set. Check IDs, years, episode order and metadata language.

If NFO and artwork already exist, configure Emby to read the appropriate local metadata and decide which tool manages it. Read-only media can supply existing NFO but cannot receive new writes. Do not begin by overwriting metadata across the entire library.

10. Direct Play, Direct Stream and transcoding#

Playback method	Server work	Typical trigger	Resource demand
Direct Play	Sends original media	Client supports video, audio, subtitles and container; sufficient bandwidth	Storage and network
Direct Stream	Keeps video encoding, remuxes; may convert audio	Container or audio incompatibility	Usually much lower than video transcoding
Transcoding	Re-encodes video; may process audio, subtitles and tone mapping	Unsupported codec, bitrate cap, subtitle burn-in, HDR to SDR	CPU/GPU, cache and storage

Not every stall is a CPU problem. Transcoding can work smoothly with suitable hardware and settings, but changes quality and adds processing.

A client's Max streaming bitrate below the file bitrate can trigger transcoding. Unsupported PGS, VobSub or certain ASS subtitles can require burn-in. HDR tone mapping has additional platform, hardware and licensing conditions. See the transcoding guide.

11. Hardware acceleration and temporary storage#

11.1 Check licensing and support first#

On most platforms, hardware-accelerated transcoding, transcoding HDR tone mapping and Backup & Restore require Emby Premiere. The official matrix lists device exceptions. Full client playback, application unlocks and server Premiere are separate concepts; check the feature matrix.

You need a supported video engine, correct driver, device permissions, container GPU access where applicable, Emby support and the necessary license. A GPU name or /dev/dri does not prove that every codec, bit depth, subtitle or HDR operation is accelerated.

11.2 Intel / AMD on Linux#

ls -l /dev/dri
getent group video
getent group render

A render node such as renderD128 is common; inspect its actual group ownership. Native Emby can join the relevant groups that exist:

sudo usermod -aG render emby
sudo usermod -aG video emby
sudo systemctl restart emby-server

Run only the group commands valid on your system. For Docker, add this peer-level block inside the service:

    devices:
      - /dev/dri:/dev/dri

Add the render node's actual numeric group to EMBY_EXTRA_GIDS and recreate the container:

cd /srv/emby
sudo docker compose up -d
sudo docker exec emby ls -l /dev/dri

Windows supports Intel, NVIDIA and AMD interfaces where supported. Linux chiefly uses Quick Sync, VAAPI and NVENC/NVDEC. Check actual AMD hardware and release support rather than promising identical behavior to Intel. See Linux acceleration and Windows acceleration.

11.3 NVIDIA#

Install the appropriate official driver on the host and verify nvidia-smi. Docker additionally requires NVIDIA Container Toolkit and a valid GPU request/runtime configuration; /dev/dri alone is insufficient.

Follow the NVIDIA Container Toolkit documentation, validate GPU access inside a container, then select supported acceleration in Emby. Driver setup differs between distributions; do not copy incompatible package commands.

11.4 A dedicated transcoding directory#

Native Linux example:

sudo install -d -o emby -g emby -m 0750 /var/cache/emby-transcode
sudo -u emby test -w /var/cache/emby-transcode

Choose /var/cache/emby-transcode in native Emby or /transcode in the Docker example. This must be a dedicated writable directory: Emby cleans its contents, so do not put media, backups or other important files there. Allow space for bitrate and concurrency rather than defaulting to a small RAM disk.

11.5 Verify a real session#

Play a file that actually triggers video transcoding. Check the dashboard's active session and its Direct Play / Direct Stream / Transcoding status. Inspect hardware_detection and ffmpeg-transcode logs for the actual decoder, encoder and errors. An idle GPU during Direct Play is normal.

Observe Intel with intel_gpu_top or NVIDIA with nvidia-smi, alongside CPU usage and transcoding output speed. Audio, subtitles and some filters may still use CPU. When asking for help, supply media details, the client, the reason for transcoding and relevant logs after removing keys, tokens and private addresses.

12. Remote access: define the boundary first#

Route	Client requirement	Public entry	Suitable use
LAN only	Trusted home network	None	Watching at home
Tailscale private network	Client installed, or subnet routing	Emby not directly public	Family and a few personal devices
Public HTTPS and reverse proxy	Normal Emby client	Controlled HTTPS endpoint	Devices that cannot use VPN
Cloudflare private network route	Cloudflare One Client and policies	Private routing	Existing Zero Trust environment

Confirm local playback first. Private networks still need application passwords and access policies; VPN membership does not justify administrator access.

12.1 Tailscale: direct private access#

Follow the official quickstart on the Emby host and remote devices, joining the same controlled tailnet.
Run tailscale ip -4 on the host for its real Tailscale IP, and tailscale status to check online state.
Open http://ACTUAL-TAILSCALE-IP:8096 remotely, or use the real device name when MagicDNS is enabled.
Configure the host firewall, tailnet access rules and Emby user's remote-access permissions. Allow only the necessary members.
Turn off phone Wi-Fi and test sign-in, playback and seeking over mobile data.

Check current official plan allowances rather than relying on fixed free-tier user/device numbers. Direct and relayed paths can perform differently; tailscale ping to the peer helps observe the route. Home upload and relay throughput can still limit playback.

Section 6's bridge example binds only the LAN IP and does not automatically listen on the Tailscale IP. Add a second ports mapping for the host's real Tailscale address, or use subnet routing below. With host networking, check Emby and firewall acceptance of that path.

12.2 Subnet router for a NAS without a client#

Install and authenticate Tailscale on an always-on Linux gateway. Enable necessary IP forwarding and limit forwarding with firewall rules. This example advertises only the NAS at 192.168.1.10 rather than the whole LAN:

sudo tee /etc/sysctl.d/99-emby-tailscale.conf >/dev/null <<'EOF'
net.ipv4.ip_forward = 1
EOF
sudo sysctl -p /etc/sysctl.d/99-emby-tailscale.conf
sudo tailscale set --advertise-routes=192.168.1.10/32

If Emby runs at 192.168.1.20, advertise that address with /32 instead. Advertise an actual subnet such as 192.168.1.0/24 only when access to the whole network is needed. Record existing advertised routes before changing the list with set.

Approve the route in the Tailscale console and allow only the intended members to the target IP and port. Linux clients may also need sudo tailscale set --accept-routes. Connect using the NAS or Emby LAN IP. Check route approval, policy and host firewall separately; see Subnet routers.

12.3 Public IPv4 / IPv6, DDNS and HTTPS#

Check your router's WAN address and ISP allocation. Private or 100.64.0.0/10 IPv4 WAN addresses can indicate upstream NAT/CGNAT; a single address comparison does not prove inbound reachability. Public IPv6 needs compatible networks at both ends, a stable address or DDNS, and explicit IPv6 firewall rules.

Point a domain to a reachable entry point, configure valid HTTPS and a reverse proxy, then verify WebSocket, Range requests and client playback. DDNS updates DNS; it does not traverse NAT or improve bandwidth. Disable automatic UPnP mapping and deliberately manage forwarding.

Use this wiki's Reverse Proxy for Emby (Linux) or Reverse Proxy for Emby (Windows Server) for full Nginx configuration. Copying Nginx settings alone cannot make an unreachable home server public. A VPS-based design also needs a working path from the VPS to the home server.

12.4 Cloudflare Tunnel limits#

Public hostnames and private network routes are different Tunnel deployments. Current official policy applies relevant video/large-file delivery terms to public hostname traffic on Free, Pro and Business plans. An ordinary public Tunnel is not the default long-term Emby video relay in this guide.

Private network routes can use Cloudflare One Client and controlled policies; the official page states that the restriction does not apply to private routes. They still need routing, clients and access controls, and remain limited by home upload. Quick Tunnel is not a permanent media-server deployment. See Cloudflare video delivery and Tunnel policy.

13. Ports, security and automatic recovery#

13.1 Common ports#

Port	Purpose	Exposure
TCP 8096	Emby HTTP	Trusted LAN / private network as needed
TCP 8920	Emby's own HTTPS	Only when enabled with a certificate
UDP 7359	Local client discovery	Often unnecessary with manual addresses
UDP 1900	SSDP / DLNA	Only for enabled discovery features
TCP 443	Reverse-proxy HTTPS	Only where the architecture needs it

8920 is not an automatically working HTTPS endpoint after installation. Do not forward discovery, DLNA or NAS administration ports to the internet. When Nginx terminates TLS, there is normally no reason to expose every Emby port publicly.

13.2 Basic protection#

Use a separate strong administrator password and least-needed family permissions. Maintain the OS and trusted plugins. Disable unused remote access and automatic mapping; use HTTPS on public endpoints. A different port can reduce some scan noise but cannot replace authentication and updates.

Logs, Compose and NFO can contain private paths or tokens; redact before sharing. Configuration backups can contain users and keys. Restrict them, consider encryption and keep them outside public web directories.

13.3 Startup and power-loss recovery#

Deployment	Verify
Native Linux	systemctl is-enabled emby-server
Docker	Daemon startup, container restart policy, NAS readiness
Windows	Login startup or a tested Windows Service
macOS	Login Items need login; system-level startup needs separate validation
NAS Apps / packages	Platform startup, unlocked volumes, ACLs and GPU allocation

Check Docker's restart policy:

sudo docker inspect emby --format '{{.HostConfig.RestartPolicy.Name}}'

unless-stopped will not automatically recover a deliberately stopped container; restart it after maintenance. Where supported, configure Restore on AC Power Loss in firmware to power on after an outage. A UPS helps but does not remove the need for orderly shutdown and backups.

Actually reboot the server and verify networking, local disks, NAS mounting, service startup and playback. An enabled flag alone does not validate unattended recovery of the whole chain.

14. Backups, restore and migration#

14.1 Back up media and configuration separately#

Media backups cover movies, home videos, photos, music and locally maintained NFO/artwork. Configuration backups cover users, playback state, favorites, libraries, databases, metadata and plugin settings. Transcoding temporary files generally do not need backup.

The official Backup & Restore plugin requires Premiere and a writable absolute backup path. Run one task manually and verify the result. It does not back up media itself; check camera uploads and recordings separately. Review plugin/database coverage and old-version compatibility in current documentation.

14.2 Docker: stop writes before copying config#

This creates a consistent configuration snapshot in /srv/emby-backups. Copy it to another device or offsite destination afterwards; the same disk is not an independent backup:

sudo install -d -m 0700 /srv/emby-backups
cd /srv/emby
sudo docker compose stop emby
sudo tar -czf /srv/emby-backups/config-$(date +%F-%H%M%S).tar.gz -C /srv/emby config
sudo cp compose.yaml /srv/emby-backups/compose.yaml
sudo cp .env /srv/emby-backups/emby.env
sudo docker compose start emby
sudo docker compose ps

Check tar succeeds. After inspecting any failure, restore the service rather than forgetting it stopped. Preserve permissions and record the image version. Do not copy only part of an actively changing database. Protect Compose and environment backups too.

For native deployment, determine the actual data directory from the dashboard or logs and stop the service before backing up all program data. Platform paths differ; do not assume a Linux path applies on Windows or macOS.

14.3 Restore and move to a new server#

Retain the old server and complete backup. Record server version, plugins, media paths and network settings.
Install a compatible version on the new host and stop it during restore.
Restore configuration and fix owner / UID/GID. Never let two servers write the same database directory simultaneously.
Restore storage mounts first and verify paths. Stable /media/Movies and /media/TV container paths reduce changes when the host layout moves.
Check users, play state, favorites, libraries and real playback. Windows/Linux path separators and layout changes may need additional migration work; copying alone is not a universal lossless migration.
Update DHCP reservations, client addresses, DDNS and the proxy. Update port-forward destinations when forwarding is used.
Retire the old server only after the new one is stable, retaining recoverable old configuration.

Perform a restore drill. Creating an archive is not proof of restorability. RAID, snapshots and configuration backups serve different purposes.

15. Troubleshooting: symptom → checks → repair#

15.1 Cannot open IP
#

Test localhost on the server, then LAN, then remote access:

systemctl status emby-server --no-pager
sudo ss -lntp | grep ':8096'
curl -v http://127.0.0.1:8096

For Docker:

sudo docker compose -f /srv/emby/compose.yaml ps
sudo docker logs emby --tail 100

If localhost fails, investigate the service, logs and port conflicts. If localhost works but LAN fails, check bind addresses, firewalls, guest isolation and the IP. NAS Apps may use a different mapped host port.

15.2 Container does not start#

Run sudo docker compose config from the project directory. Check YAML, .env numbers, source directories, bind addresses and GPU nodes. address already in use means a listener conflict; wrong bind paths mean a mount/directory problem. If /dev/dri does not exist, remove that mapping and make basic startup work first.

15.3 Missing media or Permission denied#

Check host and container independently:

ls -lah /mnt/media
namei -l /mnt/media/Movies
sudo docker exec emby ls -lah /media

No files on the host: fix the disk or NAS mount. Host files but no container files: inspect volume mappings and the running container. Files inside the container but no library items: check UID/GID, parent traversal, library paths and content type. Native Linux can test sudo -u emby ls. Do not default to chmod 777.

15.4 SMB / NFS mounting fails#

For SMB mount error(13), inspect the NAS account, credentials file, share ACLs and protocol version. For NFS, inspect exports, client allowlists, UID/GID and firewall. Use findmnt -T /mnt/media/Movies and journalctl to distinguish a local mount-point directory from actual mounted network storage.

15.5 Library becomes empty after NAS reboot#

Pause scans, restore the NAS and mount, then restart Emby. _netdev / nofail do not wait indefinitely for the NAS. Review section 8's automount and dependencies. Do not delete libraries, rebuild databases or refresh all metadata while the mount is still missing.

15.6 Hardware acceleration is absent#

Confirm a real video-transcoding session, Premiere status, hardware support and drivers. Then inspect the service identity and container GPU access, followed by hardware_detection and ffmpeg-transcode logs. No GPU usage during Direct Play is normal. Accelerated decoding alone does not prove accelerated encoding or tone mapping.

15.7 High CPU or constant transcoding#

Read the session's reason for transcoding. Test client codec support, bitrate limits, audio, subtitle burn-in and HDR conversion one at a time. Disable subtitles temporarily or choose a compatible audio track for comparison. Disabling all transcoding does not make unsupported files playable.

15.8 4K stutters while CPU is low#

Check server Ethernet, the TV's Wi-Fi/Ethernet, NAS, disk and peak bitrate. With iperf3 installed on both sides, run iperf3 -s on a trusted LAN server and iperf3 -c 192.168.1.20 on the other device; stop the test server afterwards. Do not expose the test port to the internet.

Observe iostat -xz 1 and network throughput where available, installing tools through the OS package manager. Fast sequential reads do not guarantee fast seeking or scans. Check disk sleep, SMB latency and cloud-provider throttling.

Measure home upload and the actual remote path. A roughly 30 Mbps upload cannot normally sustain a roughly 70 Mbps file directly. Start by testing a lower remote client maximum bitrate, such as 10 Mbps, and check transcoding speed and quality. Adjust using measurements and allow for multiple users, peaks and protocol overhead.

15.10 Port 8096 is occupied#

sudo ss -lntp | grep ':8096'
sudo docker ps --format 'table {{.Names}}\t{{.Ports}}'

Jellyfin or another Emby instance may be using it. Keep the intended service and select another host port for a bridge container, such as 8097

, then use 8097 in clients. Do not run two instances against the same config directory.

15.11 Incorrect artwork or slow scans#

Fix title, year, season/episode and database ID first, refreshing one test item. Slow scans can involve file count, small-file latency, sleeping disks, metadata-provider connectivity or cloud APIs. Repeated full-library refreshes can increase load. Decide whether local NFO or online metadata takes priority.

15.12 Server does not return after reboot#

On Linux check is-enabled and journalctl. For Docker check the daemon, restart policy and mounts. On Windows check the actual service identity or missing login. On Mac check Login Items and volume unlocking. Also verify firmware power recovery rather than checking only the Emby process.

15.13 Lost configuration after update or offline media after migration#

Pause changes and check whether /config still maps to the original host directory, whether the Compose project moved, and whether UID/GID changed. Offline titles usually require checking old/new media paths and mounts. Do not delete old data or initialize again; locate the correct directory, repair access and restore from a consistent backup if needed.

16. Deployment checklist#

17. Official documentation and further reading#

This guide organizes official material for home deployment. Versions, NAS interfaces and service policies can change; check the current platform instructions. Commands are configuration examples and must be verified on your equipment.