Build a Tiny M3U Playlist Linter in Python (Zero Dependencies)

Marcus Hale — Tue, 03 Nov 2026 12:26:20 +0000

M3U files look simple. They're plain text: a header, then pairs of lines where one describes a stream and the next one points to it. Because they're so easy to edit by hand, they're also easy to break. One missing URL line shifts every entry below it, a duplicated link hides in line 4,000, and a typo like htps:// fails silently in most players.

In this post we'll build m3u_check.py, a small command-line linter that:

validates the basic M3U structure
reports entries with no URL (and URLs with no entry)
flags duplicate URLs and duplicate names
warns when tvg-id is missing, so you know EPG data won't match
optionally checks every URL with a concurrent HEAD request
returns a non-zero exit code so you can drop it into CI

No pip install needed. Everything comes from Python's standard library.

A 30-second refresher on the format

An extended M3U playlist looks like this:

#EXTM3U
#EXTINF:-1 tvg-id="news.one" tvg-logo="https://example.com/n1.png" group-title="News",News One
https://example.com/live/news1.m3u8

#EXTM3U must be on the first line.
#EXTINF: starts an entry. -1 is the duration (-1 means a live stream with no fixed length).
Everything between the duration and the last comma is a set of key="value" attributes. tvg-id links the entry to an EPG (TV guide) source, tvg-logo holds an icon, and group-title sets the category.
After the comma comes the display name.
The next non-comment line is the URL.

That "next line" rule is where most bugs come from, so it's the core of our parser.

The broken playlist we'll test with

Save this as sample.m3u. It hides four problems. Try to spot them before reading on:

#EXTM3U
#EXTINF:-1 tvg-id="news.one" tvg-logo="https://example.com/n1.png" group-title="News",News One
https://example.com/live/news1.m3u8
#EXTINF:-1 tvg-id="" group-title="Sports",Sports Two
https://example.com/live/sports2.m3u8
#EXTINF:-1 tvg-id="movies.three" group-title="Movies",Movies Three
https://example.com/live/news1.m3u8
#EXTINF:-1 tvg-id="docs.four" group-title="Docs",Docs Four
#EXTINF:-1 tvg-id="kids.five" group-title="Kids",Kids Five
htps://example.com/live/kids5.m3u8

Step 1: Parse entries with a tiny state machine

We read the file line by line and keep one variable, pending, which holds the #EXTINF entry that is still waiting for its URL.

If we see #EXTINF while something is already pending, the previous entry never got a URL.
If we see a URL with nothing pending, it's an orphan.
Otherwise we attach the URL and store the finished entry.

Attributes are pulled out with one regex: ([\w-]+)="([^"]*)". It matches tvg-id="news.one", group-title="News" and so on, and dict() turns the matches into a lookup table.

Two small details make the parser more forgiving in real life:

encoding="utf-8-sig" silently strips the BOM that some Windows editors add, which would otherwise break the #EXTM3U check.
We strip() every line, so stray \r characters and trailing spaces don't create fake URLs.

Step 2: Lint the parsed entries

Once we have clean entries, the checks are short:

URL scheme. urllib.parse.urlparse gives us the scheme. Anything other than http, https, rtmp, rtsp or udp is suspicious, and that's how we catch the htps:// typo.
Missing tvg-id. The entry still plays, but players can't match it to guide data, so it shows "No information".
Duplicates. collections.Counter over URLs and names finds them in one pass, even in very large files.

Step 3: Probe URLs concurrently (optional)

Checking 2,000 URLs one by one with a 5-second timeout could take hours. ThreadPoolExecutor lets us send many HEAD requests in parallel. Network calls spend most of their time waiting, so threads work well here despite the GIL.

We use HEAD instead of GET because we only want the status code, not the video data. A few servers reject HEAD with a 405. If you see a lot of those, switching the probe to a GET that reads only the first few bytes is a simple fix.

The full script

#!/usr/bin/env python3
"""m3u_check.py - lint an M3U/M3U8 playlist and (optionally) probe its URLs."""
import argparse
import re
import sys
from collections import Counter
from concurrent.futures import ThreadPoolExecutor
from urllib.parse import urlparse
from urllib.request import Request, urlopen

ATTR_RE = re.compile(r'([\w-]+)="([^"]*)"')


def parse(path):
    """Return (entries, problems). Each entry is a dict with line, name, attrs, url."""
    entries, problems = [], []
    with open(path, encoding="utf-8-sig", errors="replace") as f:
        lines = [l.rstrip("\r\n") for l in f]

    if not lines or not lines[0].strip().startswith("#EXTM3U"):
        problems.append((1, "missing #EXTM3U header on line 1"))

    pending = None
    for n, raw in enumerate(lines, start=1):
        line = raw.strip()
        if not line or (line.startswith("#") and not line.startswith("#EXTINF")):
            continue  # blank lines, header and other directives
        if line.startswith("#EXTINF"):
            if pending:
                problems.append((pending["line"], f'"{pending["name"]}" has no URL'))
            meta, _, name = line.partition(",")
            pending = {"line": n, "name": name.strip() or "(no name)",
                       "attrs": dict(ATTR_RE.findall(meta))}
        else:  # a URL line
            if pending is None:
                problems.append((n, "URL without an #EXTINF line above it"))
                pending = {"line": n, "name": "(no name)", "attrs": {}}
            pending["url"] = line
            entries.append(pending)
            pending = None
    if pending:
        problems.append((pending["line"], f'"{pending["name"]}" has no URL'))
    return entries, problems


def lint(entries):
    problems = []
    for e in entries:
        scheme = urlparse(e["url"]).scheme
        if scheme not in ("http", "https", "rtmp", "rtsp", "udp"):
            problems.append((e["line"], f'"{e["name"]}" has an odd URL: {e["url"]}'))
        if not e["attrs"].get("tvg-id"):
            problems.append((e["line"], f'"{e["name"]}" has no tvg-id (EPG will not match)'))
    for url, count in Counter(e["url"] for e in entries).items():
        if count > 1:
            problems.append((0, f"duplicate URL x{count}: {url}"))
    for name, count in Counter(e["name"] for e in entries).items():
        if count > 1:
            problems.append((0, f'duplicate name x{count}: "{name}"'))
    return problems


def probe(entry, timeout):
    url = entry["url"]
    if not url.startswith(("http://", "https://")):
        return entry, "skipped (not http)"
    try:
        req = Request(url, method="HEAD", headers={"User-Agent": "m3u-check/1.0"})
        with urlopen(req, timeout=timeout) as resp:
            return entry, f"HTTP {resp.status}"
    except Exception as exc:  # timeouts, DNS errors, 4xx/5xx
        return entry, f"FAIL ({exc.__class__.__name__}: {exc})"


def main():
    ap = argparse.ArgumentParser(description="Lint an M3U playlist.")
    ap.add_argument("playlist")
    ap.add_argument("--check-urls", action="store_true", help="send a HEAD request to each http(s) URL")
    ap.add_argument("--workers", type=int, default=10)
    ap.add_argument("--timeout", type=float, default=5.0)
    args = ap.parse_args()

    entries, problems = parse(args.playlist)
    problems += lint(entries)

    groups = Counter(e["attrs"].get("group-title", "(none)") for e in entries)
    print(f"{len(entries)} entries in {len(groups)} groups")
    for group, count in groups.most_common():
        print(f"  {group}: {count}")

    print(f"\n{len(problems)} problem(s)")
    for line, msg in sorted(problems):
        print(f"  line {line}: {msg}" if line else f"  {msg}")

    if args.check_urls:
        print("\nURL check")
        with ThreadPoolExecutor(max_workers=args.workers) as pool:
            for entry, result in pool.map(lambda e: probe(e, args.timeout), entries):
                print(f"  {entry['name']}: {result}")

    sys.exit(1 if problems else 0)


if __name__ == "__main__":
    main()

Running it

python3 m3u_check.py sample.m3u

4 entries in 4 groups
  News: 1
  Sports: 1
  Movies: 1
  Kids: 1

4 problem(s)
  duplicate URL x2: https://example.com/live/news1.m3u8
  line 4: "Sports Two" has no tvg-id (EPG will not match)
  line 8: "Docs Four" has no URL
  line 9: "Kids Five" has an odd URL: htps://example.com/live/kids5.m3u8

All four hidden problems are caught. Notice that "Docs Four" is reported instead of silently swallowing the next entry's URL, which is exactly what many players do.

To also test the links:

python3 m3u_check.py my_playlist.m3u --check-urls --workers 20 --timeout 3

Using it in CI

The script exits with 1 when it finds a problem, so it works as a guard in any pipeline. A minimal GitHub Actions step:

- name: Lint playlists
  run: |
    for f in playlists/*.m3u; do
      python3 m3u_check.py "$f"
    done

Leave --check-urls out of CI unless you control the servers. Remote streams go up and down for reasons unrelated to your change, and flaky builds teach people to ignore failures.

Ideas to extend it

--fix mode: drop duplicates and orphan lines, then write a cleaned file.
EPG cross-check: load an XMLTV guide and report tvg-id values that don't exist in it.
JSON output: add --json so other tools can consume the report.
Group filter: --group Sports to check only one category.

Wrapping up

M3U is one of those formats that's "just text" until it isn't. A hundred lines of standard-library Python turns silent playback failures into clear, line-numbered errors you can fix in seconds. A state machine for parsing, Counter for duplicates and a thread pool for I/O are patterns you'll reuse well beyond playlists.

What would you add to it? Let me know in the comments.

This article was written with AI assistance. The code was run and the output above was verified before publishing.

DEV Community: Marcus Hale