XMLTV EPG URL for IPTV: Where to Get Guide Data and How to Add It

An XMLTV EPG URL for IPTV is a second web address, separate from your playlist, that points at a schedule file. Your playlist tells the player where the streams are. The guide file tells it what is on them and when. Two files, two URLs, and almost every blank-guide complaint on the internet starts with someone assuming there is only one.
So the honest answer to “where do I get one” is short, and it is not a list of websites. In order of how likely they are to actually work: the provider who sold you the playlist, the header line already sitting inside your playlist file, and only then an outside XMLTV file. That order matters, because the third option fails for a reason nobody warns you about — and we will get to it.
First: are you on the right page?
Guide problems all look identical from the sofa, and they are not the same problem. Find your row before you read further.
| What is happening | Where to go |
|---|---|
| You have no guide URL at all, or the one you have is dead | This page |
| You are not sure what a guide even is | What is EPG in IPTV? |
| You have a URL and want the full setup, including catch-up | IPTV EPG setup |
| The guide loads but every program is hours out | EPG wrong time |
| The guide fills in for some channels and not others | EPG not matching channels |
Still here? Then you need a source. Let us start with why you need a separate one at all.
Why the playlist cannot carry the schedule
Open your playlist in any text editor and you will see the shape of the problem immediately. A channel entry is one line of attributes and one line with a stream address. There is nowhere in it to put twenty-four hours of program titles, start times, descriptions and episode numbers — let alone seven days of them for eight hundred channels.
There is also nothing forcing the format to behave. Wikipedia’s write-up of the format is blunt about it: there is no formal specification for the M3U format; it is a de facto standard. The IPTV attributes everyone uses — group-title, tvg-logo, tvg-name, tvg-chno, tvg-id — are conventions that players agreed on, not rules anyone enforces.
One of those attributes is the hinge. tvg-id is documented as a unique identifier whose whole job is to link the channel to its channel id in XMLTV. That is it. The playlist does not contain the schedule; it contains a string that points at the schedule, assuming a schedule exists somewhere with the same string in it.

Source 1: your provider, and the URL you may already have
If your playlist came from a subscription, the guide almost certainly came with it. Providers build the guide from the same channel list they sold you, which means the ids match by construction — and matching ids are ninety per cent of the battle.
How you get it depends on how you log in:
- You log in with a server address, username and password. The guide travels with the login. Panels of this type expose the schedule on the same host as the playlist, and a player that speaks the login format fetches it for you. In most cases there is no separate URL to hunt for at all — you enter three fields and the guide arrives. If those three fields are new to you, what Xtream Codes actually is covers them properly.
- You were given a long playlist link. Look in the same place you got the link — the account dashboard, the welcome email, the reseller’s panel. The guide URL is usually printed one line below the playlist URL, and it is usually ignored.
- You have neither. Ask. One short message asking “what is the XMLTV URL for my line” is faster than an afternoon of trial and error, and if the answer is “we do not provide one”, that is genuinely useful information — it tells you to skip to source three.
Deciding between the two login styles for other reasons? M3U vs Xtream Codes compares them on more than just the guide.
Source 2: the guide URL hiding in your playlist’s first line
This one costs thirty seconds and people skip it constantly. Open your playlist file and read line one. The header line — the #EXTM3U that must be the first line of the file — is allowed to carry attributes of its own, and a very common convention is to hang the guide address off it:
#EXTM3U url-tvg="https://example.com/guide.xml.gz" You will also see it written as x-tvg-url. Neither is part of any specification — remember, there is no specification — so treat it as a hint rather than a guarantee. Two practical consequences follow. First, if that attribute is there, you already have your guide URL and you did not know it. Second, whether your player reads it automatically varies by player, so copying the value into the guide field by hand is never wrong.
While you are in there, check whether the address ends in .gz. Guide files are large and are very often served compressed; that is normal, and a player that supports XMLTV expects it. Do not unzip it and host the raw file somewhere — just paste the address as given.
Source 3: an outside XMLTV file
If your provider has no guide, the remaining option is a schedule file published by someone else. These come in recognizable types rather than one canonical list:
- Country or region files — one file covering the free-to-air and popular channels of a single country, usually rebuilt daily.
- Community-maintained collections — open projects that publish per-country files and document exactly which channels they include.
- Grabber output you generate yourself — the XMLTV project is a set of tools that pull listings from public sources and write them into this format. It is more work, and it is the only route where you control the ids completely.
- Player-bundled guides — some apps ship a built-in schedule for common channels. Convenient, and completely opaque about coverage.
The catch with all four is the same, and it is the reason “just use a public EPG URL” is bad advice given confidently by thousands of pages: an outside file was not built for your playlist. Its channel ids were chosen by whoever generated it. Your playlist’s tvg-id values were chosen by whoever built your playlist. Nothing makes those two sets of strings agree, and when they disagree the file loads perfectly and shows you nothing.
That is not a bug you can report. The XMLTV DTD — the format’s own definition — says so directly in the comment above the program element: the channel attribute references the id of a channel element, “but the DTD doesn’t give a way to specify this constraint.” A file full of programs pointing at ids that nothing in your playlist uses is a valid file. Nothing errors. Nothing warns. The guide is simply empty.
How to judge an XMLTV source before you add it
Here is the part almost nobody writes, and it is the most useful thing on this page. You do not have to trust a stranger’s recommendation, because a well-formed guide file describes itself. Open the URL in a browser (or download and open it) and read the very first element.

The root <tv> element carries a set of documented attributes, and each one answers a question you would otherwise have to guess at:
| What you read | What it tells you |
|---|---|
date | When the listings were originally produced. A date from last month means the file is abandoned, whatever the site says. |
source-info-name / source-info-url | Who supplied the listings, in human-readable form |
source-data-url | Where the machine-readable data was actually grabbed from |
generator-info-name | Which program built the file, usually as name/version |
Number of <channel> blocks | How many channels it genuinely covers, versus the number on the marketing page |
| The shape of the ids | Whether they look like anything in your playlist |
That last row is the decisive one, and there is a documented convention behind it. The DTD says a channel id must be unique and should preferably take the form of a DNS-like name without a URI scheme — which is why real-world ids look like channel-one.tv rather than 27. If a candidate file uses tidy DNS-style ids and your playlist uses bare numbers, you already know the join will fail before you paste anything.
One more thing worth checking: whether the file has <channel> blocks at all. The DTD is explicit that including them is “entirely optional — you can just leave out channel elements or provide only some of them.” A file can be full of programs and declare almost no channels, which is legal and, for your purposes, useless.
How to add the URL to a player
Every player words this differently, but the shape is identical everywhere:
- Open the settings for the playlist you already added — not the app’s global settings. The guide is attached to a playlist, not to the app.
- Find the field labeled EPG, XMLTV, Guide, or Program guide.
- Paste the full address, including
https://and including.gzif it is there. No spaces, no trailing characters. - Save, then trigger a refresh or reload of the guide rather than waiting for the automatic one.
- Give it time. A week of listings for a large channel list is a genuinely big download and parse, and on a small streaming stick it is not instant.
Then check a channel you know is popular in the region the guide covers. If a well-known channel is blank, the problem is matching, not the URL. If every channel is blank, the problem is the URL or the download.
The URL is valid and the guide is still empty
Assuming the file downloaded, there are only a handful of real causes.
The ids do not match. The overwhelmingly common one. Your playlist’s tvg-id is not identical to any channel id in the guide. Identical means identical — case, punctuation, and every character. This has its own full write-up in why some channels have no guide.
Your playlist has no ids at all. Plenty of playlists ship with tvg-id="" on every line. There is nothing to match, so no guide URL on earth will help until the ids are filled in or the player falls back to matching by name.
The names are the fallback, and names are messier than ids. The DTD requires at least one display-name per channel and allows several, noting that “names listed earlier are considered ‘more canonical’.” Wikipedia’s attribute table adds the other half: tvg-name is usually the same name repeated after the comma, “but can differ to match display-name in XMLTV.” So name-based fallback is a designed-in path — which is exactly why the decorative junk in channel names hurts. Stripping [HD], (4K) and |UHD| tags is not cosmetic if your player is matching by name.
The guide covers a different country. Obvious in hindsight, invisible at the time, especially with a file that advertises a huge channel count.
You are looking at dead entries. If a chunk of your list never plays either, the guide is not your first problem. Hiding dead channels first makes everything else easier to read.
The encoding trap: two ids that look identical and are not
This one costs people entire evenings. Wikipedia’s format notes state that UTF-8 is mandatory for playlists using the .m3u8 extension, while a plain .m3u is assumed to use the system’s own codepage. XMLTV files, meanwhile, declare their encoding at the top of the file.
The practical result: an id containing an accented character, a dash that is not a plain hyphen, or a non-Latin letter can render identically on screen in both files and differ byte for byte underneath. Your eyes say they match. The string comparison says they do not, and the string comparison is the one that counts.
If you are staring at two ids that look the same and refuse to join, that is your answer. Retyping the id by hand — rather than copying it — usually fixes it, because you replace the invisible character with an ordinary one.
What a good guide gives you beyond now and next
It is worth knowing what you are buying with the effort, because a guide file is doing more work than the two-line strip on your screen suggests.
Program entries carry titles, sub-titles, descriptions, categories, episode numbers, ratings and language details. Channel blocks can carry an icon — that is where picons come from, so a good guide can quietly fix missing channel logos as well as missing schedules. Timing is what makes the rest possible: the guide is what lets a player show a proper grid, jump to what is on later, drive catch-up, and schedule a recording by program instead of by clock. Recording a live channel is far more pleasant when the start and stop times come from the guide rather than from you guessing.
One timing detail to file away: the DTD states that when a timestamp carries no explicit timezone, UTC is assumed. That single sentence explains a large share of guides that load perfectly and sit several hours out — covered in full over on EPG wrong time.
How mtivi handles the guide URL
mtivi takes an XMLTV guide URL alongside your playlist and matches it against your channels, so the grid fills in instead of staying blank. Compressed files are expected, large lists are expected — the same engine that handles very large playlists handles the guide that goes with them.
The parts that save the most time are the boring ones. Adding the URL without typing it on a remote, using the web playlist manager, turns a five-minute exercise in arrow keys into a paste. Cloud sync means you set the guide up once and your other screens get it, rather than repeating the whole exercise per device. And if you are combining lists, merging playlists is where id collisions surface, so it is worth doing before you go guide-hunting.
What no player can do is invent listings. If your provider publishes no guide and no outside file uses your ids, the honest answer is that the grid stays empty until one of those two things changes. Any app promising otherwise is promising something the format cannot deliver.
The ten-minute checklist
- Open your playlist. Read line one. If it has
url-tvgorx-tvg-url, copy that address — you are done hunting. - No header attribute? Check your provider dashboard or welcome email for an XMLTV or EPG link.
- Still nothing? Ask your provider directly. A yes or a no both save you time.
- Only then look outside, and pick by country, not by advertised channel count.
- Open the candidate file and read its
date,source-info-nameandgenerator-info-name. - Look at the id format in its
<channel>blocks. Compare it to atvg-idfrom your own playlist. - If the two look nothing alike, stop. It will not match.
- Paste the URL into the guide field on the playlist, save, refresh.
- Wait for the parse. Check a channel you are confident the file covers.
- Blank for some channels only? That is a matching job, not a sourcing job — go to the matching guide.
Related guides
- What is EPG in IPTV? — the definitional starting point
- IPTV EPG setup — the full setup, including catch-up and time-shift
- EPG not matching channels — when the guide works for some channels only
- IPTV EPG wrong time — a guide that loads but is off by hours
- M3U vs Xtream Codes — which login format to use
- What is an IPTV player? — the top-level explainer
- Back up your player setup — so you only do this once
- Best IPTV player for Android TV — if you are still choosing an app
The format is old, loosely specified and joined together by a single string that nothing validates. Once you know that, sourcing a guide stops being a hunt for a magic link and becomes a short, checkable process — which is the whole point of reading the file’s own header before you trust it. The XMLTV project’s format page is the reference if you want to go deeper.
Frequently asked questions
Is the EPG included with my IPTV playlist?
Usually not in the same file. The playlist carries stream addresses and channel attributes; the schedule lives in a separate XMLTV file with its own URL. The exception is a server-address-plus-username login, where the guide is served from the same host and the player fetches it as part of the login, so it feels like one thing.
Where can I find an XMLTV URL?
Three places, in this order: your provider’s dashboard or welcome email; the url-tvg or x-tvg-url attribute on the first line of your playlist file; and an outside country or community XMLTV file. The first two match your channel ids by construction, which is why they are worth checking before anything else.
Why is my EPG guide empty even though the URL works?
Almost always because the ids do not match. Your playlist’s tvg-id values have to be identical to the channel id values in the guide, and nothing in either format enforces that. A guide full of programs for ids your playlist never uses is a perfectly valid file that displays nothing.
How often should an XMLTV file update?
Daily is the norm for a maintained source, since listings change and most files carry several days ahead. You do not have to take anyone’s word for it — the root element of the file carries a date attribute recording when the listings were produced. If that date is old, the source is stale regardless of what its homepage claims.
Can I use one guide URL for two different playlists?
Yes, if both playlists use ids the guide declares. Most players attach the guide to a playlist rather than to the app, so you would add the same URL in both places. Whether it works depends entirely on the ids, not on how many playlists you point at it.
What does tvg-id actually do?
It is documented as a unique identifier that links a playlist channel to its channel id in XMLTV. It is a pointer and nothing more — it carries no schedule data itself. If it is empty, or if it points at an id no guide declares, your player has nothing to look up.
My guide URL ends in .gz — is that a problem?
No, that is normal and expected. Guide files are large, so they are commonly served compressed. Paste the address exactly as given, including the extension. Do not decompress it yourself and host the raw XML somewhere else.
Can a player match channels by name instead of by id?
Many can, and the formats anticipate it. The XMLTV definition requires at least one display name per channel and allows several, noting that names listed earlier are considered more canonical, and the playlist’s tvg-name attribute is documented as something that can differ specifically in order to match a display name. Name matching is more fragile than id matching, which is why cleaning decorative tags out of channel names helps.
Two ids look identical but the guide still will not join. Why?
Probably an encoding difference. UTF-8 is mandatory for .m3u8 playlists while a plain .m3u is assumed to use the system codepage, so an accented letter or an unusual dash can look the same on screen and differ byte for byte. Retyping the id by hand instead of copying it usually resolves it.
Does a guide file also supply channel logos?
It can. A channel block in XMLTV may carry an icon element with an image address, which is where picons in the guide come from. So a good guide sometimes fixes missing logos at the same time as missing listings — though many playlists supply logos separately through the tvg-logo attribute.
Do I need a guide to record a live channel?
Not strictly — you can record by setting a start and stop time yourself. But scheduling by program instead of by clock is far more forgiving, and that only works when a guide is loaded and matched. It is one of the better reasons to get sourcing right.
Does mtivi provide a guide URL or channels?
No. mtivi is a media player. We don’t provide, sell, or include any channels, movies, series, or playlists. You add your own source, and you add your own XMLTV guide URL alongside it — mtivi’s job is to fetch that guide, match it to your channels and display it properly.
The guide loads but everything is a few hours out. Is that a sourcing problem?
No, that is a timezone problem, and it is common because the XMLTV definition says a timestamp with no explicit timezone is assumed to be UTC. The file is fine and the URL is fine. Fixing it is covered separately in the guide on a schedule that is off by hours.







