A Raspberry Pi IPTV server running TVHeadend accepts live video streams, organises them as channels with electronic program guide data, and delivers them to client devices on demand over your local network. TVHeadend sits between your video sources (whether internet-based M3U playlists or hardware tuners) and your playback devices. The Pi handles stream routing and scheduling. This guide covers hardware selection, OS setup, TVHeadend installation from the Debian repository, M3U playlist and EPG configuration, client setup, and troubleshooting the common failure points.
Last tested: Raspberry Pi OS Bookworm Lite 64-bit | May 3, 2026 | Raspberry Pi 4 Model B (4GB) | TVHeadend 4.3 | Kodi 21 (client)
Key Takeaways
- TVHeadend does not create or fix content. It routes what you give it. If an M3U stream URL is unstable upstream, TVHeadend faithfully delivers that instability to clients. Buffering problems are almost never caused by the Pi. They are almost always caused by the upstream stream provider or your local network.
- System time accuracy is not optional. TVHeadend EPG data relies on precise timestamps. If your timezone is wrong or NTP is inactive, guide entries appear at the wrong time, recordings fail silently, and channel mappings become unreliable. Verify
timedatectlbefore configuring anything else. - MicroSD cards fail quickly under IPTV workloads. Timeshifting, recording buffers, and guide data all involve frequent small writes. Use a USB SSD for TVHeadend recording storage and mount it with a stable UUID-based fstab entry.
Raspberry Pi IPTV Server: What TVHeadend Actually Does
TVHeadend is a stream router with a database. It accepts inputs (hardware tuners or internet M3U playlists), maps those inputs to named channels, associates electronic program guide data with those channels, manages user authentication, and serves streams to clients over HTTP or the HTSP protocol. It does not transcode by default. It forwards streams as received. Understanding this is important because it explains why TVHeadend cannot fix a bad upstream stream.
The two input types behave differently and have different failure modes. Internet-based M3U playlists depend entirely on the stream provider’s uptime and capacity. Hardware tuners (DVB-T, DVB-S, DVB-C) depend on signal quality and the tuner’s bandwidth limits. Most home setups use M3U playlists. Hardware tuners are better for over-the-air local channels where reliability matters more than channel count.
Hardware Requirements
Pi 4 Model B with 2GB RAM is the practical minimum. True Gigabit Ethernet and the Pi 4’s USB architecture handle multiple concurrent streams without the shared bus bottleneck that affects Pi 3 B+. With Pi 3 B+, one stream usually works and two often do not. The problem is hardware, not software.
Use an external USB SSD for TVHeadend recording storage. Format it ext4. Avoid unpowered USB hubs for SSD connections. Voltage sag causes SSD disconnects and recording failures that look like software problems. If you attach hardware tuners as well, use a powered USB hub.
Install active cooling. Sustained streaming keeps the Pi CPU under load continuously. Thermal throttling above 80 degrees C causes stuttering that looks like network problems. See Raspberry Pi 5 Cooling Guide for tested cooling options (applies equally to Pi 4 thermal management).
OS Setup and TVHeadend Installation
Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. In the advanced settings, set hostname, enable SSH, and configure credentials. After first boot:
sudo apt update && sudo apt full-upgrade -ySet the correct timezone immediately. TVHeadend EPG data timestamps are relative to system time. Wrong timezone means wrong guide entries and failed recordings:
# List available timezones
timedatectl list-timezones | grep America
# Set your timezone
sudo timedatectl set-timezone America/Chicago
# Verify NTP is active
timedatectl
# Look for: NTP service: active
# System clock synchronized: yesMount the SSD for recordings. Use UUID for a stable mount:
blkid /dev/sda1
# Note the UUID
# Add to /etc/fstab:
# UUID=your-uuid /mnt/recordings ext4 defaults,nofail,noatime 0 2
sudo mkdir -p /mnt/recordings
sudo mount -aInstall TVHeadend from the Debian repository:
sudo apt install tvheadend -yThe installer prompts for an admin username and password. Set these during installation. Running TVHeadend without credentials exposes your stream server to anything on the local network.
sudo systemctl enable --now tvheadend
sudo systemctl status tvheadendExpected result: TVHeadend shows active. Navigate to http://<pi-ip>:9981 and the TVHeadend web interface loads with a login prompt. Port 9981 is the web UI. Port 9982 is the streaming interface used by Kodi and other clients.
Set correct permissions on the recordings directory so TVHeadend can write to it:
sudo chown -R hts:hts /mnt/recordings
Configuring M3U Playlists and EPG Data
Adding an M3U IPTV playlist
In the TVHeadend web interface, go to Configuration > DVB Inputs > Networks > Add > IPTV Automatic Network. Paste your M3U playlist URL in the URL field. TVHeadend parses the playlist, creates muxes, and discovers services. This takes 2 to 5 minutes for a large playlist.
After scanning completes, go to Configuration > DVB Inputs > Services and confirm services appear. Then map them to channels: select all services and use the Map Selected button. Channels now appear under Configuration > Channel/EPG > Channels.
Expected result: Channels appear in the channel list with stream URLs. Test one by clicking the play icon next to a channel in the web interface. If it buffers or fails, the issue is with the upstream M3U URL, not the Pi setup.
Adding EPG guide data
XMLTV is the most common EPG format. Install the XMLTV tools:
sudo apt install xmltv -yIn the TVHeadend web interface, go to Configuration > Channel/EPG > EPG Grabber Modules. Enable only the grabbers you are using. Enabling unused grabbers creates conflicts. If your M3U provider supplies an EPG URL separately, configure it under Configuration > DVB Inputs > Networks and set the XMLTV URL in the playlist network settings.
After enabling EPG sources, go to Configuration > Channel/EPG > EPG Grabber and trigger a manual run. Check Program Guide to confirm data is populating. Channel names in the EPG must match channel names in TVHeadend exactly. Even minor differences (spaces, capitalisation) break the mapping. Use the channel mapping editor to fix mismatches.
Recording directory configuration
Go to Configuration > Recording > DVR Profiles > Default Profile. Set the recording system path to /mnt/recordings. Set file permissions to allow TVHeadend to write. Confirm by scheduling a short test recording.
Client Setup
Kodi with HTSP
Kodi connects to TVHeadend using the HTSP protocol, which provides native channel browsing, full guide support, and recording control. In Kodi, go to Add-ons > Install from repository > PVR clients > TVHeadend HTSP Client. Configure it with the Pi’s IP, port 9982, and your TVHeadend credentials. After enabling, Kodi refreshes and shows the TV menu populated with your channels and guide data.
VLC for testing
Before configuring complex clients, test streams with VLC. In VLC, go to Media > Open Network Stream and enter:
http://<pi-ip>:9981/stream/channel/<channel-id>VLC shows codec information, buffer behaviour, and network errors that other clients hide. If VLC cannot play a stream smoothly, no other client will. Diagnose at the VLC level before investing time in Kodi or app configuration.
Mobile and smart TV clients
Apps like TiviMate, IPTV Smarters, and GSE IPTV on Android and iOS connect to TVHeadend via the M3U stream URL or HTSP. Smart TV apps vary in codec support and error reporting. Many stop playing without explanation when a stream fails. Test each client against VLC first to confirm the streams themselves are healthy before debugging the client.
Troubleshooting
Streams buffer or drop
# Check Pi CPU and temperature during streaming
htop
vcgencmd measure_temp
# Check network throughput
iftop -i eth0
# Check TVHeadend logs
sudo journalctl -u tvheadend -n 50If CPU is under 50% and temperature is under 75 degrees C and network throughput is well under the Gigabit ceiling, the problem is upstream. The M3U stream provider is delivering an unstable stream. TVHeadend cannot fix this. Switch stream providers or use a different stream URL from the playlist for the affected channel.
EPG shows wrong times or no data
timedatectl
# Confirm NTP service: active and System clock synchronized: yes
# Force an EPG reload
# TVHeadend web UI: Configuration > Channel/EPG > EPG Grabber > Run grabber nowWrong EPG times are almost always a timezone problem. Confirm timedatectl shows the correct timezone and active NTP before checking anything else. After fixing the timezone, restart TVHeadend and force a fresh EPG grab.
TVHeadend cannot write recordings
# Check ownership of recordings directory
ls -la /mnt/recordings
# TVHeadend runs as user hts. Fix ownership:
sudo chown -R hts:hts /mnt/recordings
# Confirm the SSD is still mounted
df -h /mnt/recordingsRecording failures after working previously almost always mean the SSD disconnected and remounted under a different device path. Check dmesg | tail -20 for USB disconnection events. If the SSD is on an unpowered hub, move it to a direct Pi USB port or a powered hub.
Channels disappear after playlist update
When an M3U playlist provider updates their playlist, channel identifiers can change. TVHeadend stores channel IDs internally. If a provider renumbers streams, the existing channel mappings point to wrong or missing streams. After a playlist update, go to Configuration > DVB Inputs > Services, delete stale services, re-scan the network, and remap channels. EPG mappings also need reapplying after a full remap.
FAQ
Is this setup legal?
The Pi, TVHeadend, and the technical setup described here are legal. Whether your M3U playlist content is legal depends entirely on where the streams come from. Over-the-air broadcast channels received via a hardware tuner are legal to record for personal use in most jurisdictions. Internet-based IPTV subscriptions vary widely. Some are legitimate licensed services and some are not. The hardware and software in this guide are neutral tools.
How many simultaneous streams can a Pi 4 handle?
For M3U IPTV (no transcoding), a Pi 4 handles 4 to 6 simultaneous streams comfortably within Gigabit Ethernet bandwidth limits. TVHeadend is not the bottleneck. Network throughput and the stream provider are. For hardware tuner recording, each tuner handles one stream per frequency regardless of Pi capability.
Can I access my IPTV server remotely?
Yes, but do not expose TVHeadend ports directly to the internet. Use Tailscale to access the Pi’s local IP securely from anywhere, or put TVHeadend behind a Caddy reverse proxy with authentication. Direct port forwarding of port 9981 is a significant security risk. See Tailscale Raspberry Pi for the remote access setup.
Why does TVHeadend show services but no channels?
Services and channels are separate concepts in TVHeadend. Services are discovered streams. Channels are named, user-facing entries that point to services. After a playlist scan produces services, you must map services to channels manually or using the Map Selected button. Until mapping is complete, clients see no channels.
What is the difference between M3U and hardware tuner inputs?
M3U playlists point TVHeadend at internet stream URLs. The streams live on external servers. Hardware tuners receive broadcast signals via antenna or cable directly. M3U setups have more channels and lower hardware cost but depend on your internet connection and the provider’s uptime. Hardware tuners have fewer channels (local broadcast only) but are independent of external servers once the antenna is positioned correctly.
References
About the Author
Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.
Last tested hardware: Raspberry Pi 4 Model B (4GB), USB 3.0 SSD. Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. TVHeadend 4.3.