EPG for All Countries on GitHub: Sources & Setup Guide

If you're searching for epg for all countries github, you already know the basics — your M3U playlist loads channels fine, but every player shows "No EPG data" next to every single channel. This guide covers the real solutions: where the best open-source XMLTV aggregators live, how to wire them into your player correctly, and why most setups fail at one specific step that almost nobody talks about.

What an EPG Is and Why GitHub Hosts the Best Free Sources

Definition: XMLTV format and how players consume it

An Electronic Program Guide (EPG) is a structured file your IPTV player reads to display "what's on now" and "what's on next" alongside each channel. The format almost every player accepts is XMLTV — an open standard that's been around since 2000 and hasn't needed much updating because it does the job well.

XMLTV files are just XML. Two primary elements carry everything: <channel> defines a station with a unique ID, display name, and optional icon URL. <programme> attaches a timeslot to that channel ID with a start and stop timestamp in the format start="20260511180000 +0000" — that's YYYYMMDDHHmmss followed by a UTC offset. Players parse these elements in sequence and build the on-screen guide grid from them.

Nothing exotic, nothing proprietary. If your player says it supports XMLTV, it reads these tags.

Why community-maintained EPGs on GitHub outperform scraped alternatives

Most "EPG services" that sell or give away EPG URLs are themselves scraping broadcaster websites and reselling the data with zero transparency about freshness, coverage, or methodology. They go down with no notice, change their URL format, or quietly drop certain regions.

GitHub-hosted open-source projects are different. You can see the scraper code, the CI workflow that runs it, when the last update happened, and whether the job actually succeeded. That's real accountability. When something breaks, someone files an issue and someone else fixes it — sometimes within hours.

Community maintainers also tend to care about edge cases: non-Latin scripts, channels that air in multiple time zones, regional variants of the same broadcaster. Commercial EPG providers rarely bother with that level of detail.

How aggregator repositories pull from official broadcaster sites

Most serious aggregator projects don't invent data. They write scrapers that hit official public pages — a broadcaster's "Schedule" section, their web-based guide, or their mobile app API — and transform whatever HTML or JSON they get back into valid XMLTV. The scrapers run automatically, usually via GitHub Actions on a cron schedule. Fresh XMLTV files get committed to the repo (or uploaded to a release) every 6 to 24 hours.

That's the key insight: the data originates from the broadcaster's own public-facing systems. The GitHub project is a standardizer and aggregator, not a data fabricator.

Major Open-Source EPG Aggregators on GitHub

Repositories that aggregate sources from 100+ countries

The most useful projects for finding epg for all countries github coverage are the large multi-country aggregators. These repositories typically contain separate guide files per country or region (e.g., guides/us.xml, guides/de.xml, guides/ar.xml) plus a combined file that merges everything. Coverage often spans 80–150 countries, refreshed daily or more often.

The combined files are massive — easily 100–300 MB uncompressed for a full 7-day window. But most of these repos also publish individual country files and gzipped variants that come in at 10–30 MB. Use those whenever you can.

A good multi-country project will have an active CI badge on its README, a clearly documented update schedule, and a structured folder layout that makes it obvious which file covers which region. If none of that is present, be skeptical — it might be an unmaintained fork.

Single-country and regional repositories for niche markets

Some countries are well covered by dedicated single-country projects. These often have higher accuracy for that specific market because the maintainer actually watches those channels and notices when a scraper breaks. For regions like Southeast Asia, the MENA countries, or Eastern Europe, a dedicated regional project will usually have better channel coverage than the generic multi-country aggregator.

Search GitHub for terms like "xmltv [country name]" or "epg [country name] iptv" and you'll find them. Check when the last commit was — anything over 6 months with no activity is likely dead.

How to evaluate a repository: stars, last commit, CI status, license

Stars are a vanity metric, but low stars on a project with very recent commits might mean it's new and good. High stars on a project with no commits since 2023 means it's dead and popular. Last commit date is the real signal for living projects — you want activity within the past 2–4 weeks minimum.

Click the Actions tab. If there's a workflow called something like "Update EPG" or "Run scrapers" running on a schedule, and the last run succeeded (green checkmark), the data is actively maintained. If the last workflow run shows a red X and it was three months ago, move on.

For license: MIT and GPL are both fine for personal use and self-hosting. If there's no LICENSE file at all, treat the project cautiously — legally that means you have no explicit rights to use or redistribute the files.

How to Add a GitHub-Hosted EPG to Your IPTV Player

Locating the raw XMLTV URL on GitHub (raw.githubusercontent.com)

GitHub's regular file viewer wraps content in HTML — your player can't use that URL. You need the raw file. Navigate to the file in the repository, then click "Raw" in the top-right corner of the file view. The URL will change to raw.githubusercontent.com/username/reponame/branch/path/to/guide.xml. That's the URL your player needs.

Some repositories publish their EPG files as GitHub Release assets instead. Look in the Releases section on the right sidebar. Release asset URLs follow the pattern github.com/username/reponame/releases/download/tag/guide.xml.gz — download links, not raw content links. Both work for IPTV players that support HTTP.

Adding the EPG URL in players that support XMLTV input

Every major player handles this slightly differently, but the setting is usually called "EPG URL", "XMLTV URL", or "Program Guide Source". Tivimate, Kodi (with PVR IPTV Simple), OTT Navigator, and Spark Player all support this. Paste the raw URL, save, and trigger a refresh.

If the player accepts gzipped files (most do), always prefer the .xml.gz variant. A 200 MB file compressed down to 18 MB makes a real difference on slow connections or Android TV boxes with limited RAM.

Matching channels by tvg-id between M3U and EPG

This is where 90% of failed EPG setups actually break. The tvg-id attribute in your M3U playlist must exactly match the id attribute on the corresponding <channel> element in the XMLTV file. Case-sensitive. Character-for-character.

If your M3U has tvg-id="BBC.One.uk" and the EPG file has id="bbc1.uk", the player gets nothing. They don't match. No fuzzy matching, no smart fallback in most players — just silence.

To debug this, open both files in a text editor. Search for a channel name you know should have data. Check what ID the XMLTV uses for that channel, then find the corresponding line in your M3U and update tvg-id to match exactly. Some M3U playlist providers publish a mapping document showing which EPG IDs their channel list uses — check for that first before editing manually.

A particularly nasty variant: some EPG projects use slug-style IDs like bbc-one while M3U playlists use numeric IDs like 70400. Those can never match without a translation layer — either edit the M3U, find an EPG that uses the same ID scheme, or write a short script to generate a mapping.

Refresh intervals and cache settings

Set your player's EPG refresh interval to match how often the source actually updates — not more often. If the repository pushes new data every 12 hours, refreshing every hour burns bandwidth, wastes memory, and occasionally hits GitHub's rate limits for your IP (especially relevant if many devices on the same network all request the same raw file simultaneously). Every 12–24 hours is usually right.

When the EPG seems wrong despite a recent update, the issue is usually player-side cache. Most players have a "Clear EPG cache" or "Force refresh" option buried in settings. Use that before assuming the source data is broken.

XMLTV File Structure and Common Issues

Anatomy of a programme entry: title, sub-title, desc, category, icon

A basic <programme> element looks like this:

<programme start="20260511190000 +0000" stop="20260511200000 +0000" channel="bbc1.uk">  <title lang="en">The Nine O'Clock News</title>  <sub-title lang="en">Monday edition</sub-title>  <desc lang="en">National and international news.</desc>  <category lang="en">News</category>  <icon src="https://example.com/posters/news.jpg" /></programme>

The title element is the only required field. Everything else is optional, but desc and category make the guide much more useful. The icon element displays show art in supported players — some repositories include it, many don't.

Timezone handling and offset bugs

The UTC offset in the timestamp (+0000, +0200, -0500, etc.) is how your player translates broadcast time to your local clock. If a scraper hard-codes +0000 for a channel that actually broadcasts in +0200, every show appears 2 hours earlier than it actually airs.

DST transitions make this worse. A scraper that correctly handles +0100 for CET in winter but forgets to switch to +0200 for CEST in summer will show programs shifted by one hour for about 6 months of the year. This is one of the most common bugs in EPG scrapers — if you notice your EPG is off by exactly one hour after a clock change, this is why. File an issue on the repository with the specific channel and offset you're seeing.

Encoding issues with non-Latin scripts (Cyrillic, Arabic, CJK)

All XMLTV files must be UTF-8 encoded with the XML declaration <?xml version="1.0" encoding="UTF-8"?> at the top. When a scraper pulls program names in Arabic, Cyrillic, Chinese, or Hindi from a source and doesn't handle encoding correctly, players display mojibake — garbage characters instead of readable text.

If you see characters like пÑогÑамма for what should be Cyrillic, the file was likely encoded in Latin-1 or Windows-1252 somewhere in the pipeline. A good project will have this fixed; a hastily-written one won't. Check if the repository has open issues mentioning encoding or specific non-Latin languages before committing to it for those regions.

What to do when a country's guide is missing or stale

Open an issue on the repository describing the problem: which country, which channels, how far back the data goes stale. Most maintainers appreciate a well-written bug report far more than a one-line "this doesn't work."

Better still: submit a pull request. If the project has a scraper framework and you can figure out how one existing country scraper works, replicating it for a missing country is often straightforward. Some projects have contributed scrapers for 30+ countries this way. If fixing the existing project feels too slow, search for a regional fork or single-country project as a stopgap — use it as your EPG source for that region while the main project catches up.

Self-Hosting vs Direct GitHub Consumption

Pulling the XMLTV file directly from raw.githubusercontent.com

Direct consumption is the simplest setup. Paste the raw URL, done. The downside is that you're dependent on GitHub staying up and the repository staying public. GitHub is generally reliable, but repositories get DMCA takedown notices occasionally — a project that was available yesterday might return a 404 today. That's rare, but it happens.

There's also a rate-limiting consideration. GitHub rate-limits raw content requests by IP. If you're on a shared network (apartment building, office, dormitory) with multiple IPTV users all pulling the same 200 MB file every 12 hours, you may start seeing request failures. For personal single-household use this is usually fine.

Mirroring the file to your own server with cron

If you have a VPS, a Raspberry Pi running 24/7, or even a NAS with a scheduler, you can pull the XMLTV file on a cron job and serve it locally. A simple wget or curl command in a crontab entry, running slightly after the repository's own update schedule, means you always have a fresh cached copy:

0 6 * * * curl -s -o /var/www/html/epg/guide.xml.gz \  "https://raw.githubusercontent.com/maintainer/project/main/guide.xml.gz"

Your player then points at http://your-server/epg/guide.xml.gz instead of GitHub. Faster, more reliable, and immune to GitHub rate limits. Total setup time: about 10 minutes.

Filtering large multi-country files down to channels you actually watch

A 200 MB multi-country XMLTV file is genuinely painful on low-end Android TV boxes. The player has to parse the entire file to build the guide, and on devices with 1–2 GB RAM, that can cause slowdowns or crashes. Filtering to only the channels in your playlist is the real fix.

Extract the channel IDs from your M3U (grep for tvg-id=), then use those IDs to filter the XMLTV file. The conceptual approach: read the channel list, keep only <channel> elements and <programme> elements whose id or channel attribute appears in that list. A 200 MB file often shrinks to under 5 MB when filtered to 100–150 specific channels.

Generating a slimmer EPG with command-line tools

For the command-line approach, xmlstarlet is the right tool. A filter pass looks roughly like:

xmlstarlet sel -t \  -c "//channel[@id='bbc1.uk' or @id='cnn.us']" \  -c "//programme[@channel='bbc1.uk' or @channel='cnn.us']" \  guide.xml > filtered.xml

Python's xml.etree.ElementTree also handles this cleanly for anyone more comfortable with scripting than shell tools. Build a set of your wanted IDs, iterate the source tree once, write matching elements. For a list of 150 channels you watch, the filtering step takes under a second and the result loads instantly in any player.

Legal and Ethical Considerations

Schedule data and copyright in different jurisdictions

Program schedules — channel name, show name, start time, end time — are factual data. In most common law jurisdictions (US, UK, Australia), raw facts without creative authorship generally can't be copyrighted. The EU takes a slightly different approach through the database directive, which grants protection to databases representing substantial investment, though short factual schedules often fall below that threshold.

What does carry copyright: episode synopses written by a broadcaster's editorial team, promotional imagery, and original descriptive copy. EPG projects that include detailed episode descriptions are in grayer territory than those that include only title, time, and category. This is not legal advice — for commercial use at scale, talk to a lawyer who specializes in your jurisdiction.

Why most public EPG projects operate under fair-use precedent

Most open-source EPG projects have operated publicly for years without legal action. The prevailing pattern is that broadcasters benefit from having their schedule data accurately distributed — it drives viewership. The community projects that format and republish this data are doing something similar to what TV listings magazines historically did: aggregating publicly announced schedules for audience convenience.

That said, "hasn't been challenged yet" is not the same as "legally clear." Understand the distinction.

Respecting source broadcaster terms of service

Some broadcasters explicitly prohibit automated scraping in their terms of service. EPG scraper authors have to weigh that when writing their tools. As a user consuming the resulting XMLTV files, you're one step removed from that — but understanding where the data comes from matters if you plan to redistribute it.

Checking the repository's README for any notes about their scraping methodology and source terms is worth a few minutes of reading before you build a product or service on top of the data.

Contributing back to the open-source community

The epg for all countries github ecosystem runs on volunteer effort. If you find a bug — wrong timezone, encoding issue, a broken scraper for your country — the right move is to contribute a fix rather than just complain or quietly fork. Most maintainers are genuinely glad to get a well-documented issue or a working pull request. The projects that have the best coverage are the ones with active contributor communities, not the ones with a single overworked maintainer trying to keep 120 scrapers running alone.