Tvheadend

Last reviewed Sep 13, 2026 · 844 words

Tvheadend is rated Hard on this site, but the software is not the hard part. The tuner is. Buy a network tuner such as an HDHomeRun, or a USB stick whose chipset has a mainline Linux driver, and Tvheadend is a 20-minute setup that then runs untouched for years; the codebase dates from 2007 and behaves like it. Buy a bargain USB stick that needs a vendor firmware blob and you will spend the weekend in dmesg. Every other decision in this guide is cheaper than getting that one wrong.

Network tuners skip the driver problem entirely

A tuner that speaks SAT>IP or the HDHomeRun protocol lives on your LAN, needs no kernel driver, and can be shared by any box that wants it. Tvheadend discovers both automatically, with one caveat for Docker: discovery uses broadcast, so run the container with network_mode: host or add the tuner's IP by hand under Configuration, DVB Inputs, SAT>IP. USB tuners work fine too, they just need /dev/dvb passed through:

services:
  tvheadend:
    image: lscr.io/linuxserver/tvheadend
    network_mode: host
    devices:
      - /dev/dvb:/dev/dvb
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - /srv/recordings:/recordings
    restart: unless-stopped

The web UI is on port 9981 and the HTSP streaming protocol on 9982. The 256 MB RAM figure is real for a couple of tuners; transcoding is the only thing that pushes it up, and I would leave transcoding to the client rather than the server.

Channels appear only after four screens, in order

This is the part of the configuration curve that actually catches people. Tvheadend does not have a "scan for channels" button; it has a chain. You create a Network (DVB-T, DVB-S with your satellite, or an IPTV network pointed at an M3U URL), attach your tuner to it, and start a scan. The scan populates Muxes, the frequencies, and each mux yields Services, the raw streams. None of those are watchable yet. You then go to Services, select all, and choose Map services to channels. Only then does the Channels tab fill up. Every "Tvheadend finds nothing" forum thread I have read was someone stuck between step three and four.

For IPTV, the same chain applies, with the M3U as the network. If your provider's list has 3,000 channels, filter before mapping; a channel list that long makes the EPG grabber and Kodi both sluggish.

EPG: over-the-air is free, XMLTV is better

Broadcast EPG data arrives with the signal and covers about 7 days in most regions, which is enough for most households and requires nothing beyond ticking the OTA grabber. When the broadcast data is thin, Tvheadend can run an external XMLTV grabber. The internal cron runs it on a schedule you set, and channel names must match between the grabber output and your mapped channels, which is a one-time chore in the EPG Grabber Channels tab. Do this before you invite the family to use it; a DVR with a half-empty guide gets abandoned within a week.

Recording lands wherever you point the DVR profile

The default DVR profile writes to the container's /recordings, which is why the compose above mounts real storage there, with a user ID that can write to it. Two settings pay for themselves: a pre- and post-padding of 2 and 5 minutes for live broadcasts that overrun, and a retention rule so recordings expire rather than filling the disk. Timeshift (pausing live TV) is a separate feature that buffers to disk or RAM; on a box with 256 MB budgeted, leave it on disk.

Kodi is the reference client; Jellyfin and Plex need an adapter

Kodi's Tvheadend HTSP client is the best front end this server has, with live TV, EPG, and scheduling that feel native, and it is the reason Tvheadend is still the DVR behind so many Kodi living rooms. Jellyfin can use Tvheadend through its Live TV feature by pointing it at Tvheadend's M3U playlist (http://host:9981/playlist/channels) and XMLTV export, which works well for watching and acceptably for recording. Plex wants a tuner it recognises, so people route Tvheadend through Threadfin or its predecessor xTeVe to present a fake HDHomeRun. That extra hop is the sign you should probably record in Tvheadend and only play back in Plex.

What I'd do

An HDHomeRun on the LAN, the LinuxServer image in host network mode, recordings on the NAS with a 60-day expiry, OTA EPG first and XMLTV only if the guide has holes. Kodi on the TV boxes, Jellyfin's Live TV pointed at the same server for phones and laptops. Budget an evening for the network-mux-service-channel chain and then expect to touch the config twice a year. If your tuner needs a driver you cannot find in a stock kernel, return the tuner rather than fighting it; it is the one part of this stack that Tvheadend cannot fix for you.