mpv M3U Playlist Not Loading: How to Fix It

When an mpv M3U playlist is not loading, the player itself may be working perfectly while one part of the playlist chain fails. Common causes include incorrect relative paths, incompatible text encoding, shell quoting mistakes, inaccessible remote URLs, HLS streams mistaken for ordinary playlists, safety restrictions, network failures, and configuration or script conflicts. The fastest way to diagnose the problem is to isolate one playlist entry, launch mpv without your normal configuration, and read the terminal output before changing unrelated video, audio, HDR, or hardware-decoding settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a temporary clean test. This separates playlist problems from options in mpv.conf, input bindings, profiles, scripts, shaders, and user-installed integrations. It does not delete or permanently modify your configuration.

1.1 Open the playlist without your configuration

Open a terminal or command prompt and run the command appropriate for your system:

• Windows: mpv.exe --no-config --playlist="C:\Media\lists\test.m3u"
• Linux: mpv --no-config --playlist="/home/user/media/lists/test.m3u"
• macOS: mpv --no-config --playlist="/Users/user/Media/lists/test.m3u"

You can also pass the playlist as the input argument, such as mpv --no-config "test.m3u". Using --playlist= makes your intention explicit and can make troubleshooting easier.

Success means mpv identifies the file as a playlist, selects an entry, and begins playback or reports a specific error for that entry. If the clean command works, stop editing the playlist. The likely cause is in your normal configuration, profile, script, or launch command.

1.2 Test one playlist entry directly

Open the M3U or M3U8 file in a text editor. Ignore empty lines, comments beginning with #, and metadata lines such as #EXTM3U or #EXTINF. Copy one actual file path or URL and pass it directly to mpv:

• Local file: mpv --no-config "/path/to/video.mkv"
• Remote media: mpv --no-config "https://media.example/video.mp4"
• HLS manifest: mpv --no-config "https://media.example/master.m3u8"

If the entry fails directly, the playlist container is not the main problem. Investigate that path, URL, protocol, authentication requirement, or media source. If the entry works directly but fails inside the playlist, focus on encoding, relative-path resolution, playlist safety rules, or playlist syntax.

2. Check Playlist Format, Encoding, and Path Resolution

An M3U playlist is fundamentally a text file containing media locations. It may include local paths, relative paths, network shares, HTTP URLs, or other playlists. Small text-format differences can determine whether those locations resolve correctly.

2.1 Verify playlist file encoding

Use a capable text editor to inspect and resave the playlist. UTF-8 is the safest choice when paths contain accented characters, non-Latin scripts, or symbols. Traditional .m3u files are not guaranteed to use one universal legacy encoding, while .m3u8 conventionally indicates UTF-8.

Check for unexpected replacement characters, corrupted filenames, or a byte-order mark appearing as visible characters. Also make sure the file is plain text rather than rich text. On Windows, verify that the real filename is not accidentally playlist.m3u.txt.

Success means the paths displayed in the editor exactly match the real filenames and mpv no longer reports that entries cannot be opened. Once the playlist works after saving it as UTF-8, stop changing playback options because video output and hardware decoding were not responsible.

2.2 Understand the relative path base directory

A relative entry such as ../Movies/example.mkv has meaning only in relation to a base directory. For local playlist files, the intended base is normally the directory containing the playlist. Problems arise when a playlist was moved, generated with assumptions about another working directory, or uses path syntax from a different operating system.

For example, if /home/user/lists/weekend.m3u contains ../videos/film.mkv, the expected target is /home/user/videos/film.mkv. Confirm that this resolved path actually exists. On Windows, check drive letters, backslashes, mapped network drives, and whether the playlist was created on another computer.

As a diagnostic test, replace one relative entry with its full absolute path. If that entry starts playing, correct the remaining relative paths or move the playlist back to the directory structure for which it was created. Absolute paths are useful for diagnosis, although relative paths can be more portable when a media collection is moved as one directory tree.

2.3 Inspect syntax and line endings

Keep one media location per line. Metadata lines beginning with # are generally comments or extended M3U directives. Do not add shell-style quoting to every playlist line unless the application that created the playlist specifically requires it. Spaces can normally exist in playlist paths without surrounding quotation marks.

Most current tools understand Windows and Unix line endings, but malformed files can contain stray carriage returns or embedded control characters. If a path looks correct yet mpv says it does not exist, retype that line manually in a plain-text editor.

3. Distinguish Normal M3U Playlists From HLS M3U8 Streams

A normal M3U file is a list of media items. An HLS M3U8 manifest describes an HTTP Live Streaming presentation and may reference variant playlists, media segments, encryption information, audio renditions, and subtitles. Both are text playlists, but their failure modes are different.

3.1 Identify an HLS manifest

An HLS master playlist often contains tags such as #EXT-X-STREAM-INF. A media playlist may contain #EXT-X-TARGETDURATION, #EXT-X-MEDIA-SEQUENCE, and segment paths. These are signs that mpv must retrieve additional resources over the network rather than simply advance through a list of standalone files.

Test the M3U8 URL directly with mpv --no-config "URL". Success means mpv selects a stream variant, downloads segments, and starts playback. If the manifest opens but segments fail, inspect the log for HTTP status codes, DNS errors, TLS problems, expired tokens, or inaccessible relative segment URLs.

3.2 Check remote URLs inside a normal playlist

Copy each suspicious URL into a direct mpv command. A server may require cookies, authorization headers, a referrer, a particular user agent, or a short-lived signed token. A URL that worked when the playlist was created may have expired. Redirects can also lead to an HTML login page or error document instead of media.

Confirm that the URL belongs to a source you are authorized to access. If a browser works only because you are logged in, mpv may not automatically inherit that browser session. Use documented access methods supplied by the service rather than attempting to bypass DRM or authentication.

3.3 Evaluate yt-dlp only when the entry needs extraction

mpv can use yt-dlp for supported web pages when the executable is installed and discoverable. It is generally unnecessary for direct local files, direct media URLs, and ordinary HLS manifests that mpv can already open. If a playlist entry is a webpage rather than a media URL, test that page directly and look for messages about yt-dlp in the terminal.

Run yt-dlp --version in the same shell used to launch mpv. If the command is not found, install or update yt-dlp through its official distribution method or your trusted operating-system package manager. Do not download renamed binaries from random codec or streaming sites.

Success means the direct webpage test resolves to playable media. If the direct test still fails, the extractor may not support the site, the site may have changed, or access may require legitimate authentication.

4. Check mpv Options, Profiles, Scripts, and Safety Behavior

When the playlist works with --no-config but not during a normal launch, restore your setup selectively. Avoid deleting the entire configuration folder. A controlled comparison preserves custom input bindings, shaders, profiles, and scripts while revealing the conflicting component.

4.1 Inspect mpv.conf and profiles

Temporarily comment out playlist-related, network-related, and protocol-related settings first. Also inspect conditional profiles that activate for URLs, file extensions, protocols, or directories. An option that behaves correctly for local MKV files may interfere with network entries or playlist navigation.

Use mpv --show-profile=PROFILE_NAME to print the contents of a named profile. This helps verify inherited options without permanently applying more changes. Review launch aliases, shell functions, desktop shortcuts, and wrapper scripts too, because they may add options not present in mpv.conf.

Success means you identify one option or profile whose removal restores playlist loading. Keep that option disabled only where necessary, or narrow the profile condition so it does not affect playlists.

4.2 Review input bindings and scripts

An input binding usually does not prevent initial parsing, but scripts can replace file loading, intercept drag-and-drop actions, rewrite URLs, manipulate playlists, or invoke external programs. Move third-party scripts out of the active scripts directory temporarily, or disable them one at a time if your setup supports that workflow.

Also inspect input.conf for bindings that call loadfile, loadlist, IPC commands, or script messages. If the M3U works from a clean terminal command but fails only when opened through a custom key or launcher, that custom command is the primary suspect.

4.3 Understand safe playlist handling

mpv applies playlist safety restrictions because a playlist can point beyond its apparent source and request other local or remote resources. The --load-unsafe-playlists option relaxes these checks. Do not enable it globally merely to silence an error.

First verify that you trust the playlist and every referenced location. Then use the option for one controlled diagnostic launch: mpv --no-config --load-unsafe-playlists --playlist="test.m3u". If this alone fixes the issue, restructure the playlist with permitted paths where practical, or use the option only for a trusted playlist in a narrowly scoped command or profile.

Success means mpv loads the previously rejected entry and the log explicitly supports a safety-related diagnosis. If the same failure remains, remove the option and continue troubleshooting. It will not fix missing files, dead servers, invalid URLs, or unsupported authentication.

4.4 Avoid changing unrelated playback settings too early

Subtitle selection, audio track selection, video track selection, screenshots, HDR tone mapping, shaders, video output, and hardware decoding usually act after an entry has been opened. They are unlikely to explain a playlist that cannot resolve any entry.

However, if mpv resolves the playlist and then fails when decoding the selected item, test with conservative overrides such as --hwdec=no, --vo=gpu-next, or a platform-appropriate audio output selected according to the official manual. Change only one setting at a time. A decoded first frame or audible playback indicates that playlist resolution succeeded and the remaining issue belongs to media playback.

5. Check Operating System, Network, and File Access

5.1 Verify file and directory permissions

Confirm that your user account can read the playlist, every referenced media file, and each parent directory. On Linux and macOS, directory traversal permissions matter in addition to file readability. On Windows, check NTFS permissions, disconnected network drives, and whether the launching application has access to the mapped location.

Sandboxed application packages may have restricted filesystem or network access. Compare the packaged build with a trusted package from an official project-recommended source or your operating system's established package system. Do not install a codec pack because mpv normally supplies its decoding stack independently of generic system codec packs.

5.2 Correct shell quoting

Quote the entire playlist path when it contains spaces, parentheses, ampersands, or shell metacharacters. Quoting rules differ among Command Prompt, PowerShell, Bash, Zsh, and Fish. A command that works in one shell may be parsed differently in another.

Do not embed one shell's escape characters into the M3U file itself. Shell quoting protects command-line arguments; playlist entries are parsed by mpv and its underlying libraries. Success means the terminal shows the full intended filename rather than several broken arguments.

5.3 Test network reachability

For remote entries, confirm DNS resolution, TLS certificate validation, proxy settings, firewall rules, and VPN behavior. Test the exact URL rather than only the website's home page. Corporate networks and privacy tools may block media hosts while allowing ordinary web pages.

An HTTP 404 generally means the requested resource is missing. A 401 or 403 points toward authorization or access policy. Repeated timeouts indicate reachability, firewall, proxy, server, or routing problems. Fix the network or obtain a valid authorized URL instead of changing video-rendering settings.

6. Use Logs and Runtime Information to Find the Exact Failure

mpv's terminal output is often the most useful diagnostic tool. Launching from a terminal keeps errors visible that may disappear when the player is started by double-clicking a playlist.

6.1 Increase relevant message levels

Start with a readable verbose log:

mpv --no-config --msg-level=all=v --log-file=mpv-playlist.log --playlist="test.m3u"

Search the log for the playlist filename, the first entry, failed, error, HTTP status codes, protocol names, and messages about unsafe paths. Logs may contain private filenames, query tokens, cookies, or local addresses, so redact sensitive details before sharing them.

Success means the log reveals a specific failing layer, such as a nonexistent local path, rejected URL, failed DNS lookup, inaccessible segment, unsupported protocol, or decoder initialization error. Once the layer is known, stop altering unrelated settings.

6.2 Use the stats overlay and track list appropriately

The stats overlay is useful after an entry opens. It can show playback, decoding, dropped frames, and output details, but it cannot repair an unresolved playlist path. Similarly, track information confirms whether audio, video, or subtitle tracks were detected after demuxing.

If the terminal reports tracks and the stats overlay displays media information, the M3U loading stage succeeded. Troubleshoot the resulting file or stream as a separate playback issue. If no entry opens and no tracks appear, remain focused on playlist parsing, path resolution, access, or networking.

6.3 Compare normal and clean logs

Create one log with your standard launch and another with --no-config. Compare the command-line options, profiles, scripts, protocols, and first reported error. This comparison is more reliable than disabling many settings simultaneously because it preserves evidence of the difference.

7. Run a Clean Temporary Test Before Making Permanent Changes

Use a small test directory containing one short media file and one newly created UTF-8 playlist. Keep the filenames simple during the first test.

1. Create a directory named mpv-playlist-test.
2. Copy one media file you know mpv can play into it.
3. Create test.m3u8 as plain UTF-8 text.
4. Add the media filename on one line, using a relative path.
5. Run mpv --no-config --playlist="test.m3u8" from a terminal.
6. Replace the entry with one item from the failing playlist and test again.
7. Add further entries one at a time until the failure returns.

If the minimal playlist works, mpv's basic playlist support is functioning. The difference between the working and failing files is then likely to be a path, encoding, URL, access rule, or specific entry. If even the minimal playlist fails, preserve the log and verify your mpv installation through its trusted distribution channel.

Do not combine an application update, configuration rewrite, driver update, and playlist conversion in one attempt. After every change, repeat the same command. Stop as soon as the expected entry opens and plays, because further changes can hide the original cause or introduce a new one.

8. Quick Fix Checklist

• Run the playlist with --no-config from a visible terminal.
• Test the first real playlist entry directly in mpv.
• Save the playlist as plain UTF-8 text.
• Confirm the file is genuinely .m3u or .m3u8, not .txt.
• Resolve relative paths from the playlist's directory.
• Replace one relative path with an absolute path as a test.
• Distinguish a normal media list from an HLS manifest.
• Check remote URLs for expiration, authorization, and HTTP errors.
• Verify yt-dlp only when the entry is a supported webpage.
• Inspect profiles, scripts, wrappers, and playlist-related bindings.
• Use --load-unsafe-playlists only for a trusted diagnostic test.
• Create a verbose log before changing output or decoding options.
• Treat track, HDR, subtitle, audio, and hwdec errors as post-loading issues.
• Change one variable at a time and stop when playback succeeds.

9. Frequently Asked Questions

9.1 Why does an M3U entry work directly but fail inside the playlist?

The most likely causes are incorrect relative-path resolution, playlist encoding, hidden control characters, or safety restrictions. Compare the direct command with the exact text in the playlist, then test an absolute path and review the log.

9.2 Should an M3U8 file always be treated as HLS?

No. The extension indicates UTF-8 playlist text, but an M3U8 file can be a simple list of files or an HLS manifest. Tags beginning with #EXT-X- strongly indicate HLS. The contents and source URL matter more than the extension alone.

9.3 Can hardware decoding cause a playlist not to load?

Usually not. Hardware decoding begins after mpv resolves and opens an entry. If the log lists video and audio tracks before playback fails, try --hwdec=no as a media-playback test. If mpv cannot find or fetch the entry, hwdec is unrelated.

9.4 Why does the playlist work with --no-config?

Your normal configuration is adding the conflict. Check conditional profiles, scripts, wrapper commands, protocol restrictions, and custom load bindings. Re-enable components individually until the failure returns, then narrow or remove only the responsible setting.

9.5 Is enabling unsafe playlist loading a permanent fix?

It can be appropriate for a trusted playlist that intentionally references locations restricted by mpv's safety policy, but it should not be enabled globally without understanding the risk. Confirm the log identifies a safety restriction and scope the option as narrowly as possible.

9.6 When should I stop troubleshooting the playlist?

Stop changing playlist settings when mpv selects an entry, reports its tracks, and begins decoding or buffering it. Any remaining subtitle, audio, HDR, GPU, display-server, screenshot, or output-driver problem belongs to the opened media, not to M3U resolution. Preserve the working playlist setup and investigate that later stage separately.