iptv-org GitHub: Playlists, How to Use & Why Links Die, FreeIPTVCheck blog cover

The iptv-org GitHub repository at github.com/iptv-org/iptv is a crowd-sourced collection of links to publicly available IPTV streams from around the world. It does not host video, run a service, or sell anything. It is a plain list of URLs that any M3U-compatible player can read. This guide to iptv-org GitHub covers where the playlists live, how to open one, how to test streams before you waste time troubleshooting your player, and why a large share of the links are dead at any given moment.

📺
Want a reliable IPTV service? Skip the dead streams — try a premium IPTV service free for 24 hours. No card required.
Start Free Trial →

What the iptv-org GitHub repository actually contains

The repo holds .m3u playlist files and a database of channel metadata. Contributors submit stream URLs via pull requests. The maintainers run automated checks, but no one watches every channel 24 hours a day.

Three things the repository is not:

  • It is not a player. You need a separate app.
  • It is not a provider. It stores URLs, not video.
  • It is not a curated or verified list. Quality varies by channel and country.

If you want a broader look at how public playlists work and what to expect from them, the public IPTV playlist overview covers that in full.

Where the playlists live

The repository publishes its playlists through GitHub Pages. Here are the main ones, as plain text so you can copy them directly into your player.

Main index

All channels in a single file (adult channels excluded):

https://iptv-org.github.io/iptv/index.m3u

This file is large. Some players struggle to load it on slower connections.

Per-country playlists

Each country has its own file at:

https://iptv-org.github.io/iptv/countries/[country-code].m3u

Replace [country-code] with the two-letter ISO code in lowercase. For the United States it is us, for the United Kingdom it is gb. The full list of codes is in the PLAYLISTS.md file inside the repository.

Per-category playlists

Channels grouped by genre live at:

https://iptv-org.github.io/iptv/categories/[category].m3u

Categories include news, sports, entertainment, kids, documentary and others. The same PLAYLISTS.md file lists them all.

Per-language playlists

https://iptv-org.github.io/iptv/languages/[language-code].m3u

Use the three-letter ISO 639-3 code. English is eng, Spanish is spa.

How to open an iptv-org GitHub playlist in VLC

VLC handles M3U URLs directly with no extra setup.

  1. Open VLC.
  2. Go to Media > Open Network Stream (Windows/Linux) or File > Open Network (macOS).
  3. Paste the playlist URL, for example https://iptv-org.github.io/iptv/countries/us.m3u.
  4. Click Play.

VLC will load the channel list in the playlist panel. Click any entry to start streaming. If you see a black screen, the stream URL is likely dead. That is a content problem, not a VLC problem.

On mobile, any player that accepts M3U URLs works the same way. Enter the URL in the app’s “Add playlist” or “Add source” field.

Testing streams before you troubleshoot your setup

Before spending time adjusting player settings or checking your network, confirm the stream URL is actually live. Many iptv-org links are broken at any given time, and a dead URL looks identical to a network or player fault from the user’s side.

Use the IPTV stream checker to paste a single URL and get a fast status result. If the checker returns an error, the stream is gone. No amount of player or router tweaking will fix it.

To browse the playlist visually before committing to a player, use the IPTV channel viewer. Paste the playlist URL and you can scroll channels, check logos and filter by group without installing anything.

If streams load but buffer constantly, run the IPTV speed test to see whether your connection can handle the bitrate of the stream you are trying to watch.

This is the most common complaint about the repository, and it has a straightforward explanation.

CauseWhat it looks likeWhat to do
Broadcaster changed stream URLBlack screen, error code in playerCheck if another contributor has submitted a new URL in the repo’s issues
Broadcaster took stream offline permanentlySame as aboveThe channel will stay dead until removed from the playlist
Geo-restrictionStream works for contributors in one country, fails for youTry a different country’s playlist or confirm with the stream checker
CDN token expiryStream worked yesterday, fails todayNothing you can do client-side; the URL itself needs to be updated
Your ISP blocks the endpointError at network levelThe stream checker will also fail; try on mobile data to confirm

The iptv-org GitHub project has no SLA and no paid staff. Dead links are a structural feature, not a bug that will be fixed on a schedule.

Contributing to or reporting issues in iptv-org GitHub

If you find a broken link and want to report it, the right place is the iptv-org/iptv repository’s issue tracker on GitHub. Before opening an issue, check that the problem is with a specific channel URL, not your own connection.

To contribute a new stream URL, read the CONTRIBUTING.md file in the repository. The maintainers have specific formatting requirements. Submissions that do not follow them are closed without merging.

The project also maintains a separate database repository (iptv-org/database) that holds channel metadata such as names, logos and country codes. Errors in channel names or missing logos are reported there, not in the main iptv repo.

If you want to look up EPG data, the iptv-org/epg repository publishes Electronic Program Guide utilities. EPG availability varies by channel and region.

Frequently asked questions

Is iptv-org GitHub a legal IPTV service?

No. It is a repository of links to streams that contributors have submitted as publicly available. It does not host video, sell subscriptions or guarantee any stream is licensed in your country. Check local rules before streaming.

Why do so many channels in the iptv-org playlist show a black screen?

The repository stores URLs, not streams. If a broadcaster takes down or changes their stream URL, the link in the playlist breaks until a contributor updates it. Use the stream checker at /tools/iptv-test to confirm whether a specific URL is live before troubleshooting your player.

How often is the iptv-org GitHub playlist updated?

Contributors open pull requests continuously, so changes land daily, but no one centrally maintains every channel. Dead links can sit for days or weeks before someone removes them.

Can I use the iptv-org playlist on a Firestick?

Yes, if you install a player that accepts M3U URLs, such as TiviMate or Perfect Player. Paste the index.m3u URL into the player’s playlist settings. Performance depends on your connection, not the repository.

What is the difference between index.m3u and the per-country playlists?

index.m3u contains every channel in the repository in one file. The per-country files contain only channels tagged to a specific country, making the playlist shorter and easier to load in most players.