Practical guide · Python · M3U / M3U8
How to Validate an M3U Playlist with Python
This practical tutorial covers two ways to check an M3U or M3U8 file: run the Python command-line inspector on your computer, or use the browser-based checker without installing anything. Both focus on supported playlist text structure, not stream playback.
An M3U playlist is a text file that describes media entries. A malformed header, an incomplete #EXTINF record or a missing media location can make a playlist harder for other software to interpret. This guide shows how to check common structural problems on your own computer.
M3U Playlist Inspector is an open-source Python command-line tool that reads a local file and reports formatting issues. It does not upload playlist contents or connect to the media URLs.
Want to check a playlist without installing Python? Use the online M3U playlist checker in your browser, or open the M3U playlist editor to make local changes and download an updated file.
1. Understand the basic M3U structure
An extended M3U file commonly begins with #EXTM3U. An #EXTINF line describes the next media entry; the media location usually appears on the following line.
#EXTM3U
#EXTINF:-1,Example entry
https://example.com/media/example.m3u8
#EXTM3Uidentifies an extended M3U playlist.#EXTINFintroduces information about the next item.-1is commonly used for a live or unknown-length item.- The text after the comma is the entry display name.
- The next line contains the media location.
2. Get the Python validator
You need Python 3.9 or newer. No third-party Python packages are required.
git clone https://github.com/drxalan32/m3u-playlist-inspector.git
cd m3u-playlist-inspector
If you prefer not to use Git, download the current source archive from GitHub and extract it.
3. Run a local playlist check
Pass the path to an M3U or M3U8 text file that you own or are authorized to inspect:
python3 m3u_inspector.py path/to/playlist.m3u
Replace path/to/playlist.m3u with the real path to your own file. For an M3U8 file, pass its path in the same way:
python3 m3u_inspector.py path/to/playlist.m3u8
To display parsed entry names as well as the summary, add --show-entries:
python3 m3u_inspector.py path/to/playlist.m3u --show-entries
The project uses Python's standard library, so no third-party package installation is required. On Windows, you may need to use py or python instead of python3, depending on your Python installation.
The report summarizes entries, errors and warnings. Issues include missing media locations, missing metadata, empty display names, duplicate locations and basic #EXTINF syntax problems.
4. Export a JSON or CSV report
Use the report options to review findings later or process them with another local tool:
python3 m3u_inspector.py path/to/playlist.m3u --json report.json --csv report.csv
The JSON report includes the source filename, header status, entry and issue counts, parsed entries and issue details. The CSV report contains one row per detected issue, with severity, line number, issue code and message. Store these reports securely if the playlist contains private information.
JSON is useful for scripts and structured workflows. CSV can be opened in spreadsheet software. Keep exported reports private if they contain sensitive information.
5. Understand common playlist problems
- Missing header: an extended playlist is expected to start with
#EXTM3U. - Incomplete entry: an
#EXTINFrecord is not followed by a media location. - Missing metadata: a media location appears without a preceding
#EXTINFrecord. - Empty display name: the metadata separator exists but no entry name is supplied.
- Duplicate location: the same media location appears more than once.
- Invalid duration: an
#EXTINFduration is not a finite number.
How to interpret the command's exit code
0: no structural errors were found. Warnings may still be present.1: one or more structural errors were found.2: the input file could not be read, or an output report could not be written.
If a command returns an error code, read the printed issue lines first. They include the severity, source line number and a short explanation to help you locate the problem.
Run the project's tests (optional)
From the repository root, run the built-in unit tests to check the local Python installation and project test suite:
python3 -m unittest discover -s tests -v
6. Validate an M3U playlist online in your browser
If you do not want to install Python or use a terminal, open the online M3U playlist checker. Paste playlist text or select a local .m3u or .m3u8 file. The browser tool processes the text locally in your tab; it does not upload the playlist.
The online checker and Python CLI are separate interfaces. Both report supported structural issues, but their checks and report formats are not necessarily identical. Use the CLI when you need repeatable local commands and JSON or CSV issue exports; use the browser checker for a quick manual inspection.
7. Know what a structural validator cannot tell you
A clean structural report does not prove that a media URL is online, playback works, a file is secure, or content is licensed. This tool does not make network requests or verify ownership. Use it only with playlists you are authorized to inspect.
Frequently asked questions
Can I validate an M3U8 file?
Yes. The inspector reads local UTF-8 text files, including M3U and M3U8 playlist files. It checks the supported structure; it is not a complete HLS protocol validator.
Does it test whether a stream is working?
No. It does not connect to media URLs, test playback or check availability.
Are my playlist contents uploaded?
No. The command-line tool processes the file locally and does not send its contents to an external service.
For exact commands and report details, read the usage guide or the M3U and M3U8 format reference.
Also read M3U vs M3U8: what is the difference? to understand playlist extensions and encoding.
View the source code on GitHub →
Related tools: After checking the structure, you can analyse playlist entries and metadata, merge M3U files, or convert a playlist to CSV or JSON.