How to Install xTeVe on Synology NAS: A Complete Setup Guide

Running xTeVe on a Synology NAS is one of the more practical ways to manage IPTV streams and deliver an M3U playlist to media apps like Plex or Emby. The process involves Docker, some basic networking knowledge, and a bit of configuration — but once it's running, xTeVe handles playlist parsing, EPG (Electronic Program Guide) data, and stream proxying from a single, always-on device.

Here's what you need to know before you start.

What xTeVe Actually Does

xTeVe is an M3U proxy server. It sits between your IPTV provider and your media software, translating raw M3U playlists and XMLTV guide data into a format that apps like Plex DVR and Emby Live TV expect. Without something like xTeVe, Plex and Emby have limited ability to manage large IPTV channel lists, filter unwanted channels, or pull in accurate guide data.

When installed on a Synology NAS, xTeVe runs as a persistent background service — no need to keep a PC or laptop on to maintain your streams.

Prerequisites Before You Begin

Before installing anything, confirm your environment is ready:

• Synology NAS model that supports Docker (DSM 6.2 or later; most x86-64 models qualify — ARM-based Synology units typically cannot run Docker)
• Docker package installed from Synology Package Center
• An active M3U playlist URL from your IPTV provider
• An XMLTV EPG URL (optional but recommended for guide data)
• A basic understanding of port mapping and file paths within DSM

📋 Not all Synology models support Docker. Check Synology's compatibility list for your specific unit before proceeding.

Step 1: Install Docker on Your Synology

Open Package Center in DSM and search for Docker. Install it. Once installed, Docker appears in your main application menu. This is the environment where xTeVe will live.

Step 2: Pull the xTeVe Docker Image

Open Docker, navigate to Registry, and search for xteve. The most widely used image is dnsforge/xteve or alturismo/xteve — both are community-maintained. Pull your preferred image by double-clicking it and selecting the latest tag.

Once downloaded, the image appears under the Image tab.

Step 3: Create and Configure the Container

Click Launch on the image to begin container setup. This is where most of the meaningful configuration happens.

Key settings to configure:

Port mapping tells your NAS which local port to expose for xTeVe's web interface. Port 34400 is xTeVe's default. If that port conflicts with another service on your network, you can remap the local port to something else (e.g., 34401) while keeping the container port at 34400.

Volume mapping links folders on your NAS to folders inside the container. This ensures your xTeVe configuration survives container restarts or image updates. Create these folders in File Station before launching the container.

Step 4: Access the xTeVe Web Interface

Once the container is running, open a browser and navigate to:

http://[your-NAS-IP]:34400/web 

The first-time setup wizard walks you through:

1. Adding your M3U playlist URL
2. Setting EPG/XMLTV source URLs
3. Mapping channels to guide data
4. Configuring stream buffer settings

xTeVe generates a local M3U URL and an HDHomeRun device emulation URL — these are what you'll paste into Plex or Emby to connect live TV.

Step 5: Connect xTeVe to Plex or Emby 🎬

In Plex, go to Settings → Live TV & DVR → Add Device. Plex will detect xTeVe if it's on the same network, or you can enter the HDHomeRun URL manually.

In Emby or Jellyfin, go to Live TV settings, add an M3U tuner, and paste xTeVe's generated M3U URL. Add the XMLTV EPG URL from xTeVe's settings page for guide data.

Variables That Affect How Well This Works

Getting xTeVe running is one thing. How well it performs depends on several factors:

• NAS hardware: Older or lower-powered Synology units may struggle if xTeVe is buffering multiple streams simultaneously while Plex is also transcoding
• Network bandwidth: xTeVe's stream buffer pulls data from your IPTV source and re-serves it locally — your NAS needs enough upstream and downstream headroom
• IPTV provider stability: xTeVe can only proxy what the source delivers; unstable M3U sources result in buffering regardless of NAS performance
• Number of concurrent streams: xTeVe supports configurable stream limits; exceeding your provider's simultaneous stream allowance causes failures
• DSM version and Docker compatibility: Newer DSM versions (DSM 7.x) changed some Docker permission behaviors, which can affect volume mapping and container startup if not accounted for

DSM 7 Permission Considerations

On DSM 7, Docker containers no longer run as root by default, which can cause permission errors when writing to mapped volumes. If your container fails to start or xTeVe can't write its config, check that the shared folder permissions allow the Docker user to read/write. Some users resolve this by setting folder permissions explicitly via File Station or by adding the PUID and PGID environment variables in the container settings, matching them to a DSM user account.

What Your Setup Determines

A basic single-user household with a stable IPTV source and a mid-range x86 Synology will generally find this setup straightforward. A home with multiple concurrent viewers, a lower-powered NAS, or an unreliable IPTV provider introduces tradeoffs that only your specific environment can reveal. The hardware you're working with, the number of streams you need to support, and how much tinkering you're comfortable with all shape what this looks like in practice.