An IPTV EPG (Electronic Program Guide) is the on-screen schedule that tells you what is playing now and what comes next across your channels. Without a working EPG, every channel just shows a blank slot or a generic title, and catch-up TV usually stops functioning entirely.
How an IPTV EPG actually works
Your IPTV app pulls two separate files to build what you see on screen: an M3U playlist (the channel list with stream URLs) and an XMLTV file (the schedule data). The XMLTV file is a structured XML document containing a list of programmes, each tagged with a channel ID, a start time, a stop time, a title, and sometimes a description or rating.
The app matches each channel in your M3U to a channel entry in the XMLTV file using a shared ID string, often called the tvg-id. When those IDs match, the guide appears. When they don’t, the channel plays fine but shows no schedule.
Most IPTV apps, including TiviMate, IPTV Smarters, GSE Smart IPTV, and Perfect Player, follow the same basic process:
- Load the M3U playlist
- Fetch the EPG URL (either embedded in the M3U header as
x-tvg-urlor entered manually) - Parse the XMLTV file and match channel IDs
- Display the guide grid
The EPG URL is usually an HTTP or HTTPS address pointing to a .xml or .xml.gz file. Gzipped files are common because full EPG files for large channel lists can be several hundred megabytes uncompressed.
Common IPTV EPG problems and fixes
Most EPG failures fall into a small set of categories. The table below maps each symptom to its usual cause and the fix.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Blank guide on all channels | EPG URL is wrong or dead | Update the EPG URL in app settings, then force a refresh |
| Guide works on some channels, blank on others | tvg-id mismatch between M3U and XMLTV | Edit the M3U to match IDs, or use an EPG source built for your provider |
| Guide shows yesterday’s schedule | App has cached old data | Clear the EPG cache in the app, set auto-refresh to 24 h |
| Guide shows, but wrong channel names | Channels mapped to the wrong XMLTV entry | Manually remap channels in the app’s EPG settings |
| App crashes when loading EPG | File too large to parse in memory | Switch to a gzipped EPG source, or use an app that handles large files |
| Catch-up TV missing even with a guide | Provider does not support catch-up, or catchup tag absent from M3U | Confirm catch-up support with your provider |
Fixing a dead EPG URL
If your EPG URL has stopped working, paste it directly into a browser. An error or an empty page confirms the source is down. Your options are:
- Contact your IPTV provider for an updated URL
- Find a public XMLTV repository that covers your region and swap to that
- Use your app’s built-in guide mapping if it has one (TiviMate and IPTV Smarters both do)
Fixing channel ID mismatches
Open your M3U file in a plain text editor and look at the tvg-id value on each #EXTINF line. Then open the XMLTV file and check the id attribute on each <channel> tag. The values need to match exactly, including capitalisation.
If your M3U has tvg-id="BBC.One.uk" but the XMLTV file lists the channel as bbc1.uk, the app cannot link them. You either edit the M3U, edit the XMLTV, or use a middleware tool to remap them.
You can check your M3U playlist structure with the IPTV channel viewer, which parses your playlist and lists each channel’s metadata, including tvg-id values, so you can spot mismatches quickly.
IPTV EPG formats: XMLTV vs JTV
XMLTV is the standard format and is what almost every modern IPTV app expects. JTV, a binary format, is older and mainly associated with Russian-language IPTV apps. If you are using an app aimed at English-speaking markets, you almost certainly need XMLTV.
Within XMLTV, there are minor structural variations. Some EPG files include detailed sub-title, rating, and episode-numbering tags. Others include only the title and time slot. Both are valid XMLTV. The richer data just gives you more to read in the guide; it does not affect whether the guide loads.
Gzipped EPG files
An EPG URL ending in .xml.gz serves a compressed version of the same data. Most modern apps handle this transparently, but older or lower-powered devices, including some Android boxes and earlier Fire TV generations, can time out while decompressing a large file. If your guide loads on your phone but not on your TV box, file size is worth suspecting. Try finding an EPG source that covers fewer regions, which produces a smaller file.
How to check whether your streams are healthy separately from the EPG
A broken EPG does not mean broken streams, and a working EPG does not mean streams are working. They are independent. If you want to confirm your stream URLs are actually responding before troubleshooting the guide, run your M3U through the IPTV stream checker. It tests each stream URL and reports which ones return a valid response and which ones time out or return an error.
This matters because if your streams are down, fixing the EPG will not help. Conversely, if only the guide is broken but streams are fine, you know the issue is purely in the metadata layer.
If you are on an Xtream Codes setup and need to convert it to an M3U format to run it through a checker or load it into a different app, the M3U to Xtream converter handles that translation.
Setting up an IPTV EPG for the first time
If you have a working M3U playlist but no EPG configured yet, the process differs slightly by app but follows the same logic throughout:
- Find the EPG URL. It is sometimes in your provider’s welcome email, sometimes embedded in the M3U header as
x-tvg-url, and sometimes you need to ask the provider directly. - Open your app’s settings and find the EPG or Guide section.
- Enter the URL. The app will download and parse the file.
- If channels do not match automatically, use the app’s manual mapping tool to link each channel to its guide entry.
- Set an automatic refresh interval so the guide stays current.
In TiviMate, EPG is set per playlist under Settings, then Playlists, then the specific playlist entry. In IPTV Smarters, it is in the Xtream or M3U account settings. GSE Smart IPTV has a standalone Remote Playlists section where you enter the EPG URL alongside the M3U URL.
When the EPG URL is already in the M3U
Some providers embed the EPG URL in the M3U header using the x-tvg-url tag. The first line of the file looks like:
#EXTM3U x-tvg-url="https://example.com/epg.xml.gz"Apps that support this tag will pick up the EPG URL automatically when you load the playlist. If your app did not pull it in, check whether it has an option to read the x-tvg-url tag. Not all apps enable this by default.
Frequently asked questions
What is an IPTV EPG? An IPTV EPG (Electronic Program Guide) is the on-screen schedule that shows what is playing now and what comes next on each channel. It works by pulling an XMLTV-formatted file from a URL and matching each listing to a channel in your M3U playlist.
Why is my IPTV EPG not loading? The most common causes are an expired or wrong EPG URL, a mismatch between the channel IDs in your M3U and the EPG file, and an app that has cached old data. Refresh the EPG inside your app settings, then check the URL is still active.
How often should I refresh my EPG? Most IPTV apps let you set an auto-refresh interval. Once every 24 hours is usually enough. If your guide stops showing titles mid-day, the EPG source may have changed its update schedule or gone offline.
Can I use a free EPG source? Yes. Public XMLTV repositories list EPG feeds for many countries. The catch is that free sources can go offline or drop channels without notice, so you need a backup URL ready.
Does a broken EPG affect playback? No. The EPG is metadata only. If a channel plays fine but shows no guide data, the stream itself is healthy. Use the stream checker to confirm playback status separately from guide data.