EPG · 7 min read
IPTV EPG and XMLTV — how the guide works and why it sometimes vanishes
The EPG is the second-most-asked-about thing in IPTV, right after buffering. It's also the thing where the smallest config mistake makes the most visible failure — a fully working subscription with a blank guide looks broken even when every channel plays perfectly.
By Bennett Prosacco, Founder · Last reviewed
What an EPG actually is
On cable TV, the on-screen guide is broadcast alongside the video. On IPTV there is no broadcast — the player downloads a separate file that lists every channel, every programme on that channel, and the times each programme starts and ends. That file is the EPG, and the standard format for it is XMLTV.
The XMLTV file lives at a URL given to you by your provider. Every IPTV player you can install on a Fire Stick, smart TV, or phone has a setting that accepts that URL and refreshes it once or twice a day.
How EPG and channels stay matched
The EPG file lists programmes against channel IDs— not channel names. Your M3U playlist also lists every channel against an ID. The player matches IDs from the EPG to IDs in the playlist, and that's how "Sky Sports Football" ends up showing the right schedule.
This is also the most common source of partial EPG failures — when a provider rotates channel IDs without updating both files, the IDs stop matching and some channels go blank. Xtream Codes sidesteps this entirely by serving both the playlist and the EPG from the same database with always-matching IDs.
Common EPG failures and the actual fix
Almost every guide issue maps to one of these five symptoms.
| Symptom | Cause | Fix |
|---|---|---|
| Guide is completely blank | EPG source URL hasn't been added to the player | Settings → EPG → Add Source → paste the XMLTV URL from your provider |
| Some channels have guide, others don't | Channel IDs in the M3U don't match the IDs in the XMLTV file | Use Xtream Codes instead — IDs match automatically |
| Guide is hours / days behind | EPG cache hasn't refreshed since the last update | Settings → EPG → Force Refresh (or wait 24h for auto-refresh) |
| Programmes are at the wrong time | Player timezone mismatched with EPG file timezone | Player Settings → Time Zone → set to match your local timezone |
| Guide loads then disappears | XMLTV URL returns 404 or times out on refresh | Test the URL in a browser — if it fails, ask provider for a fresh link |
Loading a custom EPG
If your provider's EPG is incomplete or you want a more detailed schedule for sports / news / a specific region, you can substitute a custom XMLTV URL. Plenty of free XMLTV mirrors exist for major regions — search "XMLTV UK" or "XMLTV US" and you'll find them.
The catch is what we covered in the previous section: channel IDs in your custom EPG must match the IDs in your playlist. If they don't, you'll see the new programmes against the wrong channels (or no channels at all). Most modern players have a manual "EPG mapping" screen for fixing this on a channel-by-channel basis.
Easier: switch to Xtream Codes and let the provider handle EPG matching automatically.
Frequently asked
What is an IPTV EPG?
An EPG (Electronic Programme Guide) is the on-screen TV guide that shows what's on each channel now and what's coming up. In IPTV, the EPG isn't broadcast over the air like with cable — it's a separate file (or API endpoint) that the player downloads and displays alongside the live streams.
What is XMLTV?
XMLTV is the standard file format for IPTV guide data. It's an XML file (sometimes gzipped as .xml.gz) listing every channel ID, every programme title, and the start/end times. Almost every IPTV player on every platform speaks XMLTV.
Why is my IPTV guide blank?
Three common reasons, in order of likelihood: (1) the EPG source URL was never added in player settings; (2) the URL is correct but returns no data because your subscription is paused/expired; (3) the player cached an empty response 24 hours ago and hasn't tried again. Force-refreshing the EPG fixes case 3 immediately.
How do I add an EPG to TiviMate?
TiviMate → Settings → EPG → EPG Sources → Add → paste the XMLTV URL given by your provider. TiviMate then refreshes the EPG automatically every 12 hours. If you're on Xtream Codes, EPG is pulled by default and you don't need to add a separate source.
How do I add an EPG to IPTV Smarters?
IPTV Smarters → Settings → EPG → Type → choose XMLTV → paste the URL. Smarters can also auto-detect the EPG when you log in with Xtream Codes credentials. If both are set, Xtream Codes wins.
Can I use a custom EPG instead of my provider's?
Yes — any XMLTV URL works. Useful if your provider's EPG covers fewer channels than you want, or if it has the wrong timezone. The catch is that channel IDs in the custom EPG must match the IDs in your playlist, otherwise programmes won't line up with the right channels.