Setting up live television streams through custom M3U playlists often leaves cord-cutters with missing TV schedules, blank channel bars, and no idea what program is currently playing. That is where an Electronic Program Guide (EPG) becomes essential.
Among all open-source solutions available today, the iptv-org epg project stands out as the most reliable, comprehensive, and completely free XMLTV resource for cord-cutters worldwide. Managed on GitHub by an active open-source community, iptv-org provides structured program data for thousands of television channels across hundreds of countries.
This complete tutorial covers what iptv-org EPG is, how to choose the right guide links, how to configure it on popular streaming platforms, and how to fix common matching and sync errors.
---
What is IPTV-org EPG and How Does It Work?
An Electronic Program Guide is a digital menu that displays scheduled program details, broadcast times, descriptions, and metadata for live television channels. The iptv-org epg project is a dedicated sub-repository of the popular iptv-org project. It uses automated scraper bots to gather program data from official broadcaster websites and public television guides worldwide, consolidating that information into standardized XMLTV files.
When you add an EPG link to an IPTV media player, the app downloads this XML file, reads the channel tags, and matches them to your stream playlist.
Key Characteristics of IPTV-org EPG
- Universal Compatibility: Outputs data in standard XMLTV (
.xml) format, making it compatible with almost every modern IPTV application. - Granular Organization: Guides are divided by country, region, language, and individual channels, allowing you to load only the guide data you actually need.
- Automated Daily Updates: Automated GitHub workflows refresh program schedules daily, providing accurate listings up to seven days in advance.
- Open Source and Free: No subscriptions, API keys, or registration requirements.
---
How to Locate the Best IPTV-org EPG Links
Because loading a single file containing global program data for tens of thousands of channels would crash most streaming devices, iptv-org splits its EPG files into specific sub-directories.
To get the best performance, you should select the specific regional or language-based XML file matching your channel list rather than a master file.
Finding Your Link
- Go to the official GitHub repository at
github.com/iptv-org/epg. - Open the
guidesdirectory in the repository files. - Search for your country's two-letter ISO code or specific language code.
Here are common examples of raw URL structures provided by the project:
- United States:
https://iptv-org.github.io/epg/guides/us.xml - United Kingdom:
https://iptv-org.github.io/epg/guides/uk.xml - Canada:
https://iptv-org.github.io/epg/guides/ca.xml - Spain:
https://iptv-org.github.io/epg/guides/es.xml
Standard .xml vs. Compressed .xml.gz
Most directories offer both standard .xml and compressed .xml.gz files.
If your streaming hardware (such as an Nvidia Shield, Apple TV, or Fire TV Stick 4K) and app support compressed feeds, use the .xml.gz URL. Compressed files reduce file transfer size by up to 80%, speeding up guide downloads. If your player displays an error when parsing compressed files, stick to the standard .xml address.
---
How to Add IPTV-org EPG to Popular Streaming Apps
Configuring your player to read program guides only takes a minute. Here are the step-by-step instructions for the most popular cord-cutting software.
Setting Up on TiviMate IPTV Player
- Open TiviMate and navigate to Settings > EPG.
- Select EPG sources > Add source.
- Choose URL and enter your selected iptv-org URL (for example:
https://iptv-org.github.io/epg/guides/us.xml). - Select Done.
- Go back to Settings > Playlists, click your active playlist, scroll to EPG sources, and ensure your newly added iptv-org guide is enabled.
- Return to Settings > EPG and click Update EPG.
Setting Up on OTT Navigator
- Launch OTT Navigator and open Settings (gear icon).
- Go to Provider > EPG.
- Select Add EPG source and choose XMLTV.
- Paste your iptv-org URL into the address field and assign a friendly label.
- Save the configuration and force a manual refresh from the main settings menu.
Setting Up on Kodi (PVR IPTV Simple Client)
- Open Kodi and navigate to Settings > Add-ons > My Add-ons > PVR Clients.
- Select PVR IPTV Simple Client and click Configure.
- Go to the EPG Settings tab.
- Set Location to Remote Path (Internet Address).
- Click XMLTV URL and type or paste your iptv-org link.
- Click OK and restart Kodi to import the schedule.
---
How to Fix Common IPTV-org EPG Sync and Mapping Issues
Even with a working guide link, you may run into missing show descriptions or incorrect broadcast times. Here is how to fix the most common issues:
1. Unmatched Channel IDs (tvg-id)
IPTV players connect streams to guide listings by matching the tvg-id tag inside your M3U playlist with the channel id inside the XMLTV file. If your playlist names a channel HBO.us but iptv-org labels it HBO.east, the schedule will show as "No Information."
- Fix: Manually assign the guide source inside your player. In apps like TiviMate or OTT Navigator, long-press the channel with missing guide data, select Assign EPG (or Edit EPG), search for the channel name in the iptv-org database, and confirm the match manually.
2. Timezone Offsets (Incorrect Show Times)
If your guide shows the evening news airing at 3:00 AM, your app is misinterpreting the time zone offsets provided in the XML file.
- Fix: Open your app's EPG settings and locate Time Offset or Time Shift. Shift the offset by positive or negative hours (e.g.,
+5or-4) until live show titles match real-time broadcasts.
3. Outdated or Corrupted Cache Data
If TV listings stop updating after a few days, your application's internal database cache may be corrupted.
- Fix: Navigate to your player's EPG menu, select Clear EPG, and then immediately click Update EPG to download a fresh XML file from GitHub.
---
Frequently Asked Questions
Is IPTV-org EPG legal and safe to use?
Yes. The iptv-org project only compiles publicly available program schedules broadcast by network websites and public TV guides. It contains no video streams, copyrighted media files, or illegal content.
Why are program listings blank for some of my channels?
Blank listings happen when your M3U playlist lacks matching tvg-id tags, or when iptv-org does not currently monitor that specific regional channel. You can manually assign channels within your player or submit a channel request directly on the iptv-org GitHub issue tracker.
How often should I set my app to update the EPG?
Setting your IPTV application to refresh EPG data once every 24 hours is recommended. This keeps schedule changes up to date without placing unnecessary bandwidth load on your device or the GitHub hosts.
---
Conclusion
Using iptv-org epg is one of the easiest ways to upgrade a generic live streaming setup into a sleek, professional digital cable experience. By pairing your custom channel playlists with localized XMLTV links from iptv-org, you get clean, accurate program guides complete with show descriptions and schedule timelines. Choose your regional URL, map any missing tvg-id tags inside your player, and enjoy a fully functional TV guide on all your devices for free.
