What is an XMLTV file?

An XML file of TV listings: a list of channels, then a list of programmes, each with a start time and the channel it belongs to. IPTV players read it to build the TV guide.

Why does my XMLTV guide show the wrong times?

XMLTV times can carry a time-zone offset; if none is given, the format assumes UTC. A guide written without offsets, or with the wrong one, shifts every programme. Fix the device clock first, then use your player’s guide offset or a tvg-shift value.

How does XMLTV connect to my M3U playlist?

Through ids. Each channel in the guide has an id, and each channel in the playlist has a tvg-id. When they match exactly, the player puts those listings on that channel.

XMLTV Explained: The TV Guide Format IPTV Players Use

XMLTV explained: the TV guide format IPTV players use

When your IPTV player shows what’s on now and next, the listings almost always come from an XMLTV file. It’s a plain XML format, maintained by the open-source XMLTV project, that lists channels and the programmes on each. Understanding its two building blocks, and how it writes times, explains most guide problems: empty channels, wrong times and slow loading.

Updated 2 October 2026 · 2 min read

Also available in Dansk · Norsk · Svenska

What an XMLTV file looks like

<tv generator-info-name="example">
  <channel id="news.example">
    <display-name>Example News</display-name>
  </channel>
  <programme start="20261002180000 +0100" stop="20261002183000 +0100" channel="news.example">
    <title>Evening News</title>
    <desc>The day’s headlines.</desc>
  </programme>
</tv>

If TV guides are new to you, start with what is EPG. The XMLTV project’s DTD, the formal definition of the format, sets out the structure:

<tv> wraps everything: channels first, then programmes.
<channel> must have an id and at least one <display-name>; it can add an icon and a web address.
<programme> must have a start time and a channel; a stop time is optional. Inside, at least one <title>, then optional sub-titles, descriptions, categories, episode numbers and more.

Times and time zones

The DTD says times follow one format, loosely based on ISO 8601: YYYYMMDDhhmmss, or a shorter leading part of it, with an optional time zone on the end, such as +0100. If there’s no time zone, UTC is assumed.

That rule explains many “wrong time” guides. A guide written in UK local time but without an offset is read as UTC, so in summer every programme appears an hour out. Fix the device’s clock and time zone first, then correct what’s left with the player’s guide offset or the playlist’s tvg-shift. See EPG showing the wrong time.

Channel ids: the link to your playlist

Each channel’s id must be unique, and the DTD recommends a DNS-like name. Your M3U playlist links to it through tvg-id, which Kodi’s IPTV Simple client describes as the identifier used to map a channel to the EPG data.

Match character for character. Don’t rely on a player ignoring differences in capitals or spaces.
One mismatch, one empty channel. If a playlist channel has no tvg-id, or one the guide doesn’t contain, it shows no listings. See EPG not available for this channel.

Where XMLTV files come from

Your provider. Most IPTV providers publish a guide address alongside the playlist; with an Xtream Codes login, many players fetch it automatically. See EPG URL explained.
Other guide sources. Community and commercial sources publish XMLTV files for many countries. See IPTV EPG sources.
Your own tools. The XMLTV project publishes utilities to obtain, generate and process listings, and home servers such as Jellyfin accept XMLTV guide data. See stream Freeview around your home.

Size and speed

A guide for thousands of channels over a week is a large file, and big files are often compressed for download. Large guides load slowly on budget sticks. Hide channel groups you don’t watch, and reduce the number of guide days if your player allows it. See EPG not loading.

Sources

Facts on this page were checked against these sources. Details were correct when checked; apps and devices change, so we review this page regularly.