mpv Filename Starts With Dash Not Playing: How to Fix It

When a local media filename begins with a dash, mpv may interpret that filename as a command-line option instead of a file to open. For example, a file named -sample.mkv can produce an unknown-option error, unexpected behavior, or no playback at all. The fastest fixes are to add an explicit relative-path prefix such as ./ on Linux or macOS and .\ on Windows, or to place -- before the filename to stop option parsing. If those fixes work, stop there. Subtitle settings, HDR profiles, hardware decoding, scripts, and output drivers do not need to be changed.

If the problem continues after the filename is clearly passed as a path, then the dash may only be exposing a second issue involving shell quoting, a frontend, a playlist, permissions, a malformed file:// URL, or the media itself. This guide starts with the smallest possible test and expands troubleshooting only when the result justifies it.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin in a terminal so you can see exactly what mpv receives and what it reports. Change to the directory containing the affected file, then run a clean test without loading your normal configuration.

1.1 Test on Linux or macOS

Suppose the file is named -sample.mkv. Use either of these commands:

mpv --no-config ./-sample.mkv
mpv --no-config -- -sample.mkv

The first command changes the argument from a dash-leading name into an explicit relative path. Because the argument starts with ./, mpv recognizes it as a path rather than an option. The second command uses the conventional end-of-options marker. Arguments following -- are treated as files or URLs instead of mpv options.

Success means the file opens and plays, or mpv gets far enough to report a genuine decoding, track, or output error. If playback starts normally, the filename parsing problem is solved. Stop changing settings and use one of these forms in your command, alias, script, or launcher.

1.2 Test on Windows

In PowerShell or Command Prompt, use an explicit relative path:

mpv --no-config ".\-sample.mkv"

You can also test the end-of-options marker:

mpv --no-config -- "-sample.mkv"

Quoting is especially important when the filename contains spaces, parentheses, ampersands, or other characters the shell may process. A full Windows path also avoids the leading-dash ambiguity because it begins with a drive letter or directory prefix:

mpv --no-config "C:\Media\-sample.mkv"

If the prefixed or full path works, mpv itself is working. Do not reinstall mpv, install codec packs, change the GPU driver, or disable hardware decoding for this symptom.

1.3 Understand what the dash means to mpv

Command-line programs normally use arguments beginning with - or -- for options. A filename such as -fullscreen-test.mp4 resembles an option even though it is a valid filesystem name. Quoting the bare filename protects it from shell splitting, but quoting alone does not necessarily stop mpv from interpreting the resulting argument as an option.

For that reason, this command can remain ambiguous:

mpv "-sample.mkv"

Prefer an explicit path or --. Quoting and option termination solve different problems.

2. Check Whether an mpv Setting Is Actually Involved

A dash-leading filename is usually an argument-parsing issue, not a video, audio, subtitle, or rendering issue. Only investigate settings after mpv --no-config ./-sample.mkv, its Windows equivalent, or the -- form has passed the filename to mpv successfully.

2.1 Config files, profiles, and command-line options

If the file plays with --no-config but fails under your normal command, your configuration or wrapper is contributing to the failure. Compare these tests:

mpv --no-config -- ./-sample.mkv
mpv -- ./-sample.mkv

When only the first works, inspect mpv.conf, enabled profiles, command aliases, and launcher arguments. Look for malformed options, profile conditions based on filenames, or a script that rewrites the playlist. Do not delete the entire configuration folder. Temporarily comment out one relevant line or disable one component at a time.

If you start mpv with a named profile, inspect the profile before assuming the filename is at fault:

mpv --show-profile=profile-name

Replace profile-name with the profile you use. Success means you identify a specific setting that differs between clean and configured playback. Once that setting is corrected, retest and stop if playback works.

2.2 Input bindings, scripts, and frontends

An input binding normally acts after mpv starts, so it rarely explains why a terminal command mistakes a filename for an option. It can matter when a binding uses loadfile, calls an external script, or assembles a shell command. The binding or script must preserve the filename as one argument and must not concatenate it into an unsafe command string.

Frontends, file managers, media libraries, and desktop launchers can introduce the same mistake. A frontend may run something equivalent to mpv -sample.mkv instead of supplying an absolute path. Test the file directly in a terminal. If the direct command works but the frontend fails, update the frontend's mpv command template or report the argument-handling problem to its developer. The frontend should pass an absolute path, add a relative-path prefix, or insert -- before file arguments.

2.3 Subtitles and audio or video tracks

Subtitle options such as --sub-file can have the same leading-dash problem when the external subtitle filename begins with a dash. Pass an explicit path:

mpv ./movie.mkv --sub-file=./-english.srt

For a separate audio file, apply the same principle to the relevant external-file option. If the main file opens but no picture, sound, or subtitles appear, inspect the available tracks rather than continuing to alter filename syntax. mpv prints track information in the terminal, and the interactive stats display can help confirm what is selected.

A successful filename fix is indicated by mpv identifying the container and tracks. Missing tracks, unsupported formats, or deliberately disabled selections are separate problems.

2.4 Hardware decoding, HDR, shaders, and output drivers

Hardware decoding, GPU output, HDR conversion, shaders, and display profiles operate after mpv has accepted and opened the file. They cannot normally make a dash-leading argument look like a filename. Do not disable hwdec, remove shaders, or rewrite HDR settings merely because an unknown-option message appears.

Investigate these components only if the explicit path is accepted and mpv then reports decoder initialization, GPU context, shader compilation, or video-output errors. At that point, compare your normal command with a clean --no-config run. If both fail after the file is opened, the issue has moved beyond filename parsing.

2.5 yt-dlp, URLs, playlists, streams, and screenshots

yt-dlp is generally relevant to supported online URLs, not ordinary local files. A local file beginning with a dash should not require yt-dlp. If a wrapper incorrectly sends that local filename through a URL workflow, correct the wrapper rather than replacing yt-dlp.

Playlist entries containing relative dash-leading names should use unambiguous paths relative to the playlist's expected working directory. When generating playlists or IPC commands, preserve each filename as a distinct value rather than composing an unquoted command line.

Screenshot output settings can also encounter dash-leading names if you deliberately configure such a template or output path. That does not prevent the input media from opening unless a script treats the screenshot name as another command-line argument. Keep input-path troubleshooting separate from output-file troubleshooting.

3. Check Paths, Quoting, Permissions, and External Conditions

If mpv recognizes the argument as a path but cannot open it, read the new error literally. A message such as “file not found” indicates a path or working-directory problem, while “permission denied” points to operating system access. This is progress because the original option-parsing ambiguity has been removed.

3.1 Verify the current directory and exact filename

On Linux or macOS, list filenames in a way that makes unusual characters visible:

pwd
ls -lb

On Windows PowerShell, use:

Get-Location
Get-ChildItem -Name

Check capitalization on case-sensitive filesystems, the extension, spaces, and hidden characters. Copying a name from formatted text can introduce typographic quotes or a Unicode dash that differs from the ordinary ASCII hyphen-minus.

If ./-sample.mkv fails because the terminal is in another directory, either change directories first or provide the absolute path. Success means mpv reports the correct file path and begins probing the media.

3.2 Use shell quoting correctly

Put the complete path inside one pair of quotes:

mpv --no-config -- "./-sample video.mkv"

Do not quote only part of the path, and do not embed decorative quotation marks copied from a document. In scripts, use arrays or native process argument APIs when available. They preserve argument boundaries more reliably than a single command string.

3.3 Treat a single dash as a special case

A filename consisting of exactly one dash, -, is special because mpv commonly treats it as standard input. The -- marker stops option parsing, but it does not necessarily remove the special meaning of the standalone stdin argument.

To address an actual local file named -, use an explicit path:

mpv --no-config ./-

On Windows, use:

mpv --no-config ".\-"

Success means mpv opens the filesystem object rather than waiting for piped input.

3.4 Avoid unnecessary file URL conversion

A file:// URL can make a local resource unambiguous, but it introduces URL syntax and percent-encoding requirements. Spaces, percent signs, hash characters, platform-specific drive notation, and non-ASCII characters can make a manually constructed URL incorrect.

Prefer a normal explicit path for local files. If a frontend supplies a file:// URL, verify that it creates a valid absolute URL and encodes special characters correctly. Do not simply prepend file:// to an arbitrary relative path and assume it is equivalent.

3.5 Check permissions and media limitations only when indicated

If the path is accepted but access is denied, verify that your user account can read the file and traverse its parent directories. On macOS, a terminal application may also need permission to access protected folders. On Windows, files on network shares or controlled folders may be subject to account or security restrictions.

GPU drivers, display servers, audio backends, network access, and file corruption become relevant only after mpv opens the input or clearly attempts the appropriate connection. For local dash-leading files, an option-parsing error occurs earlier and should be fixed first.

4. Use mpv Diagnostics Without Drowning in Output

The normal terminal output often contains enough information. Look first for unknown options, failure to recognize a command-line argument, file-not-found errors, permission failures, and demuxer or decoder messages.

4.1 Increase logging selectively

To capture a reproducible clean run, use:

mpv --no-config --msg-level=all=v --log-file=mpv-dash-test.log -- ./-sample.mkv

On Windows, replace the final path with .\-sample.mkv. The log may include local paths and other environment details, so review it before sharing it publicly.

If the log shows the file being opened, the dash parsing problem is fixed. Any later error should be investigated according to its subsystem, such as demuxing, decoding, audio output, or video output.

4.2 Use track information and the stats overlay appropriately

mpv lists detected video, audio, and subtitle tracks in terminal output. During playback, the default stats overlay can provide rendering, timing, and decoder information. These tools help with high-bitrate playback, dropped frames, hardware decoding, and track selection, but they do not correct command-line parsing.

Use them only when playback begins or mpv successfully probes the file. If mpv still calls the filename an unknown option, return to the explicit path or -- fix.

5. Run a Clean Temporary Test Before Changing Multiple Options

A controlled test prevents unrelated customizations from obscuring the result. Do not start by removing config directories or uninstalling scripts. Instead, run this sequence:

1. Open a terminal in the file's directory.
2. Confirm the exact filename.
3. Run mpv with --no-config and an explicit path prefix.
4. If necessary, repeat with -- before the filename.
5. Run the same explicit path without --no-config.
6. Reintroduce frontend commands, profiles, scripts, and extra options one at a time.

This sequence separates three outcomes. If the first clean test works, basic mpv playback and filename handling are sound. If clean playback works but configured playback fails, inspect the configuration. If both commands accept the path but fail later, troubleshoot the reported media, permission, decoder, output, or hardware problem.

Stop as soon as the file plays under the environment you actually use. Additional changes can create new problems and make the original solution harder to identify.

6. Quick Fix Checklist

• Use ./-filename.mkv on Linux or macOS.
• Use .\-filename.mkv on Windows.
• Place -- before a bare dash-leading filename.
• Quote the complete path when it contains spaces or shell-sensitive characters.
• Use ./- or .\- for a real file named only -.
• Test with --no-config before editing configuration files.
• Pass absolute paths from frontends, launchers, scripts, playlists, and IPC clients.
• Prefer filesystem paths over manually constructed file:// URLs.
• Investigate subtitles, hwdec, HDR, drivers, and output backends only after mpv opens the file.
• Rename the file only when the calling application cannot pass it safely.

7. Frequently Asked Questions

7.1 Why does quoting the filename not always fix it?

Quotes tell the shell to keep text together as one argument. They do not inherently tell mpv that the argument is a filename. After the shell removes the quotes, mpv may still receive -sample.mkv and treat it as an option. Use ./-sample.mkv, .\-sample.mkv, an absolute path, or --.

7.2 Should I use the path prefix or the double dash?

Either can work. An explicit path is highly readable and also handles a file named exactly -. The -- marker is convenient when several remaining arguments are filenames, but all mpv options must appear before it. For scripts and frontends, passing absolute paths is often the most robust approach.

7.3 Why does the file work in a terminal but not in my frontend?

The frontend is probably constructing arguments differently. It may pass a bare filename, lose quoting, use the wrong working directory, or create an invalid file URL. Configure it to send an absolute path or ask its developer to preserve arguments correctly. A successful direct terminal test is strong evidence that mpv and the media file are functional.

7.4 Can a dash-leading subtitle filename cause a similar problem?

Yes, particularly when the subtitle is supplied as a separate command-line argument. Use an explicit path in the option value, such as --sub-file=./-english.srt. If mpv loads the subtitle track after that change, no video-output or decoder changes are needed.

7.5 Is renaming the file a valid fix?

Renaming works, but it should be the last resort rather than the first recommendation. It may break playlists, references, automation, subtitle matching, or library records. Rename only when an inflexible frontend or external tool cannot pass dash-leading names correctly and cannot be configured or updated.

7.6 What should I do if the explicit path still does not play?

Read the new terminal error and classify it. File-not-found errors call for path verification. Permission errors call for access checks. Demuxer or decoder errors may indicate an unsupported or damaged file. Audio and video output errors concern the relevant backend or GPU environment. Once mpv displays the correct path and attempts to open it, the original dash-leading filename problem has been resolved.