📡 Tvheadend Complete Setup 2026

Tvheadend (TVH) is a TV streaming server backend for Linux. It:

• Accepts input from DVB-T/C/S tuners, IPTV (M3U), SAT>IP, and Unix pipes
• Manages channels + EPG centrally
• Schedules DVR recordings
• Serves channels to clients (Kodi, Plex, Jellyfin) via the HTSP protocol or HTTP streams
• Has a web interface for management
• Open source since 2012, actively maintained

Compared to Threadfin: Tvheadend is far more powerful (multi-tuner, DVB support) but more complex. Threadfin is simpler for IPTV-only.

• Linux server — Ubuntu Server 22.04 LTS or 24.04 LTS
• A Raspberry Pi 4/5, NAS, or x86 mini-PC works fine
• At least 2GB RAM, 8GB storage for the OS
• For DVR: extra storage (USB/SMB/NAS)
• An M3U URL and/or DVB tuner hardware

sudo apt update
sudo snap install tvheadend

Then open in your browser: http://server-ip:9981

# Add the Tvheadend PPA
sudo add-apt-repository ppa:tvheadend/tvheadend
sudo apt update
sudo apt install tvheadend

# During install: enter admin user + password
# The service starts automatically on port 9981 (web) + 9982 (HTSP)

version: "3"
services:
  tvheadend:
    image: linuxserver/tvheadend
    container_name: tvheadend
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - ./config:/config
      - ./recordings:/recordings
    restart: unless-stopped

1. Open http://server-ip:9981 in your browser
2. The wizard starts automatically:
   • Language → English
   • Network IP → leave default (auto-detect)
   • Admin user → username + strong password
   • User access → create a read-only user for apps
3. The wizard asks for a tuner — choose "IPTV" (no DVB hardware) or "DVB" if you have a tuner card

1. Configuration → DVB Inputs → Networks → Add
2. Type: IPTV Network
3. Fill in:
   • Network name: e.g. "Provider X"
   • Maximum Input streams: 5 (simultaneous count)
   • Maximum Number of services: 5000 (channels)
   • Service identifier: auto
4. Save
5. The Muxes tab → Add → Auto IPTV Network → URL = your M3U URL
6. Save → Tvheadend scans the channels automatically

1. Configuration → Channel/EPG → EPG Grabber Modules
2. Enable External: XMLTV
3. The EPG Grabber tab → Cron multi-line: 0 */6 * * * (every 6 hours)
4. External Grabber Path: default /usr/bin/tv_grab_xmltv
5. Or: use the xmltv socket import from your own script
6. Save → manually trigger the first run

Channel mapping

Configuration → Channel/EPG → EPG Grabber Channels → match a channel with its EPG ID.

1. Configuration → Channel/EPG → Channels
2. For each channel: double-click to edit
   • Name (display name)
   • Number (channel number)
   • Icon URL (logo)
   • EPG source mapping
3. Or in bulk: Configuration → Channel/EPG → Services → "Map services" button

1. Configuration → Recording → Digital Video Recorder Profiles
2. Edit the default profile:
   • Recording system path: /recordings/$t
   • Title: enabled
   • Subtitle: enabled
   • Episode: enabled
   • Pre-recording padding: 2 min
   • Post-recording padding: 10 min
3. Save
4. Schedule a recording: go to the EPG → click a programme → "Record"

1. In Kodi: Settings → Add-ons → My Add-ons → PVR clients
2. Select Tvheadend HTSP Client
3. Enable + Configure:
   • Host: server IP
   • HTTP port: 9981
   • HTSP port: 9982
   • Username + Password from Tvheadend
4. Save → Restart Kodi
5. The TV menu in Kodi now shows the Tvheadend channels + EPG

Tvheadend serves an HTTP M3U at http://server-ip:9981/playlist/channels.m3u and XMLTV at http://server-ip:9981/xmltv/channels.

Or: use Threadfin as a middle layer for HDHomeRun emulation toward Plex.

"No free tuner"

• Increase "Maximum Input streams" in the IPTV network
• Check whether several clients are claiming the same tuner

Stream stutter

• Configuration → Stream → Stream Profile → MPEG-TS Pass-through
• Avoid transcoding unless truly needed

EPG missing

• Check the EPG Grabber log: Configuration → Debugging
• Wrong channel EPG mapping → set it manually per channel