M3U Playlists Explained: Format, Tags and Common Errors

An M3U playlist is a plain text file that lists media streams, one entry after another, so a player knows what to load and how to label it. It is the standard way IPTV player apps import a channel list, and it is easy to read once you know the handful of tags involved.

This guide explains the format, the common attributes, the difference between an M3U playlist and an HLS .m3u8 manifest, how to edit one safely and how to fix typical errors. Every example uses example.com and made-up channel names.

Quick answer: An M3U file starts with #EXTM3U. Each channel is a #EXTINF line (duration, attributes, display name) followed by a stream URL on the next line. Attributes such as tvg-id, tvg-logo and group-title link the channel to guide data, a logo and a category.

What does an M3U file look like?

#EXTM3U x-tvg-url="https://example.com/guide/epg.xml.gz"
#EXTINF:-1 tvg-id="ExampleNewsHD.uk" tvg-name="Example News HD" tvg-logo="https://example.com/logos/example-news.png" group-title="News",Example News HD
https://example.com/streams/example-news-hd.m3u8
#EXTINF:-1 tvg-id="ExampleSport1.uk" tvg-name="Example Sport 1" group-title="Sport",Example Sport 1
https://example.com/streams/example-sport-1.ts

Reading it line by line:

• #EXTM3U is the header and must be the first line.
• #EXTINF:-1 begins a channel entry. The number is the duration in seconds; -1 means unknown or continuous, which is typical for live streams.
• The attributes follow, written as name="value".
• After the comma comes the display name the player shows.
• The next line is the stream address.

The "M3U" name comes from MP3 URL, a list of audio files, and the extended #EXT tags were added later. Files saved as UTF-8 may use the .m3u8 extension.

What do the attributes mean?

These attributes are conventions that many players follow, not a single enforced standard, so support differs between apps. A player that ignores an attribute simply skips it. Some players also support extra tags such as tvg-shift for time offsets or tvg-chno for channel numbers; check your app's documentation before relying on them.

What are the catch-up attributes?

Catch-up (watching a programme that has already aired) is signalled in some playlists by attributes such as catchup, catchup-days and catchup-source, which tell a supporting player how to build the address for past programmes. These are player-specific conventions, so a playlist that works in one app may not offer catch-up in another. See our guide to catch-up, timeshift and recording.

What is the difference between an M3U playlist and an HLS .m3u8 file?

Both use the same file format family and often the same extension, which causes confusion.

An HLS manifest is generated and refreshed by the server for each stream, so you never edit it. A channel playlist is the list you manage. A channel entry in your playlist can point to an HLS manifest, as the first example above does. Related reading: what is IPTV?.

How do I edit an M3U file safely?

1. Make a copy first so you can go back.
2. Use a plain text editor, not a word processor. On a Mac, TextEdit must be set to plain text; VS Code, Notepad++ or Sublime Text avoid the problem.
3. Keep every #EXTINF line directly above its address, with no blank line between.
4. Do not alter the quotation marks around attribute values. Smart quotes break parsing.
5. Save as UTF-8 so accents in channel names survive.
6. Re-import into your player and check a few entries.

To remove a channel, delete both its #EXTINF line and the address beneath it. To reorder, move the pair together.

What are the most common M3U errors?

Also keep in mind that playlists are only a list of addresses. Your rights to the content they point to depend on the licensing of the source; read is IPTV legal?.

Where can I get help?

Ask in the EPG and guides forum. If you share a file, replace every real address and name with example.com and fake names first, and never post logins or tokens.

How do I check that a playlist is well formed?

A quick manual check catches most problems before you import a file into a player:

• The very first line is #EXTM3U, with nothing before it, not even a blank line.
• Every #EXTINF line is followed directly by exactly one address line.
• Attribute values are in straight double quotes, and there is a comma before the display name.
• Addresses begin with a scheme such as https:// and contain no spaces.
• The file is saved as plain UTF-8 text.

You can also open the file in a media player that supports playlists, such as VLC, and see whether the entries load. A text editor's search function helps you find a stray character or duplicate entries.

Why do some playlists have thousands of lines?

Playlists can grow large because every channel needs two lines, and attributes add length. Large files are slower to load and harder to manage on low-powered devices. If a player struggles, split the file into smaller playlists by category, or remove entries you never watch. Keep the original copy untouched so you can rebuild a smaller version when needed.

Can I use relative paths or local files?

Yes, for your own content. A playlist can point to local files or network shares you own, such as a home media server, and that is a legitimate use of the format. For your own library, the format works like a music playlist. Players differ in how they handle relative paths, so test with a short list first. Home streaming setups are covered in our Plex and Jellyfin guide.