mpv Command Line Option Ignored: How to Fix It

When an mpv command-line option is ignored, the cause is usually not the video itself. The option may be written in an outdated form, placed after an end-of-options marker, changed by a config or profile, misquoted by the shell, or passed incorrectly by a graphical frontend. In other cases, mpv accepts the option but cannot produce the requested result because a track, external program, output driver, permission, or hardware capability is unavailable. The steps below isolate command-line parsing first, then investigate the subsystem controlled by the option. After each test, note what success looks like and stop changing settings as soon as the command behaves correctly.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin in a terminal rather than a desktop shortcut, file manager, launcher, or third-party frontend. A terminal lets you see exactly what mpv receives and whether it reports an unknown option, a parsing error, or an attempt to open the option text as a filename.

1.1 Use Modern Long-Option Syntax

Modern mpv commands should use two hyphens for long options. When an option takes a value, the clearest form is --option=value. For example:

mpv --no-config --volume=50 "video.mkv"

This command removes the normal configuration from the test and sets an easily observable value. Success means the file opens at 50 percent software volume and the terminal does not report that --volume=50 is a filename or unknown option.

Avoid relying on legacy single-dash forms such as -volume 50. Some historical syntax may still work in particular contexts, but a single dash can create ambiguity, interact badly with wrappers, or fail with options that expect current syntax. Retype the hyphens manually as plain ASCII characters. Text copied from formatted documents can contain an en dash or another Unicode character that only looks like a hyphen.

1.2 Test an Option With a Visible Result

Replace your complicated command temporarily with one option whose effect is obvious:

mpv --no-config --fullscreen=yes "video.mkv"

If fullscreen applies, basic option parsing works. You can then test the original option in the same clean command. Boolean options commonly support forms such as --fullscreen=yes and --fullscreen=no, while many also have a dedicated negated form such as --no-fullscreen. Check the installed mpv manual for the exact accepted values.

If mpv says it cannot open a file whose name resembles your option, inspect the characters, spelling, option position, and any -- marker. Do not move on to GPU or codec troubleshooting until mpv recognizes the token as an option.

1.3 Understand the End-of-Options Marker

A standalone -- tells command-line programs that subsequent tokens are positional arguments rather than options. This is useful when opening a file whose name begins with a hyphen, but it also causes genuine options placed afterward to be treated as filenames.

mpv --no-config --volume=50 -- "-sample.mkv"

In this example, --volume=50 is parsed as an option, while -sample.mkv is treated as a filename. If the volume option were placed after the standalone marker, it would no longer be parsed as an option. Success means every intended option appears before --, and only file paths or URLs appear after it.

2. Check the Setting Directly Related to the mpv Player Issue

Once basic parsing works, test the exact feature. An accepted option can appear ineffective when another setting overrides it or when the media lacks the resource the option needs.

2.1 Config Files, Profiles, and Option Precedence

mpv can load settings from its main configuration, profiles, protocol-specific sections, file-extension sections, watch-later data, and command-line arguments. Scripts and input bindings can also change properties after startup. First compare these commands:

mpv --no-config --your-option=value "video.mkv"
mpv --your-option=value "video.mkv"

If the first works and the second does not, the command-line parser is functioning. A loaded configuration component is changing the result. Inspect mpv.conf, enabled profiles, scripts, and file-specific behavior rather than reinstalling mpv or changing drivers.

To inspect a named profile, use:

mpv --show-profile=profile-name

This prints the profile's contents without requiring you to activate it blindly. Look for the same option, its negative form, or a related setting that selects a different output path. Success means you identify the conflicting line or establish that the profile is unrelated. Stop after disabling or correcting the specific conflict. Do not delete the entire configuration directory as a first response.

2.2 Input Bindings and Scripts

An input.conf binding may change a property as soon as you press a key. Lua or JavaScript scripts can also modify playback properties during startup, file loading, or track changes. If an option works with --no-config, temporarily disable only the suspected script or binding and repeat the command.

Remember that --no-config is a diagnostic test, not necessarily the final solution. Depending on how mpv and scripts are installed, system-wide components may require separate investigation. Terminal output can reveal which scripts load. Success means the option remains active once the specific conflicting action is removed or adjusted.

2.3 Subtitle and Track Options

A subtitle option cannot select a track that does not exist. Likewise, audio and video selectors depend on the available tracks and their identifiers. If --sid, --aid, --vid, language preferences, forced-subtitle rules, or external subtitle loading seems ignored, inspect the track list during playback.

Use mpv's on-screen track selection controls or the console, and review terminal output for detected tracks. Check whether an external subtitle path is correct and readable. Relative paths are resolved from the process's working directory, which may differ when mpv is launched from a frontend.

Success means the requested track is listed and selected. If the desired language or track is absent, no command-line selector can create it. Stop modifying selector syntax and supply a valid external track or use an available one.

2.4 Video Output, Hardware Decoding, HDR, and Shaders

Options for --vo, --gpu-api, --hwdec, HDR handling, shaders, and display behavior can be accepted but fall back when the chosen backend or hardware path is unavailable. Run the command from a terminal and look for messages about decoder initialization, GPU contexts, shader compilation, or fallback to software decoding.

Test the feature independently. For example, compare automatic hardware decoding with hardware decoding disabled:

mpv --no-config --hwdec=auto "video.mkv"
mpv --no-config --hwdec=no "video.mkv"

If software decoding works but the requested hardware path does not, parsing is not the problem. Investigate supported codecs, bit depth, chroma format, GPU drivers, display server, and output backend. With HDR, also verify that the source contains appropriate metadata and that the operating system, display path, and output configuration support the intended result. Success should be confirmed by terminal status or mpv properties, not merely by judging brightness.

2.5 Online URLs, yt-dlp, and Network Streams

For website URLs, mpv may rely on yt-dlp to resolve media. An option can appear ineffective if URL extraction fails before normal playback begins. Confirm that the URL is quoted, especially when it contains &, ?, or shell-sensitive characters:

mpv --no-config "https://example.com/watch?v=123&list=456"

Without quotes, a shell may interpret part of the URL as syntax and never pass it to mpv. If yt-dlp is required, use a trusted installation source and verify that the executable is available to the same environment that launches mpv. A frontend can have a different PATH from your interactive terminal.

For direct network streams, determine whether authentication, certificates, redirects, firewall rules, or protocol support are blocking access. Success means mpv resolves the URL and begins reading the stream. If extraction or network access fails first, stop changing playback options until that dependency works.

2.6 Screenshot Options and File Destinations

Screenshot options often fail because the output directory does not exist, is not writable, or is interpreted relative to an unexpected working directory. Test with an absolute path that your user account can write to. Quote paths containing spaces.

Also distinguish between configuring screenshots and taking one. A format or template option controls future screenshots, but it does not necessarily trigger capture. Success means mpv reports a saved screenshot and the file appears at the expected location.

3. Check Shell, Frontend, File, and Operating System Boundaries

3.1 Quote Arguments for the Active Shell

Shell quoting rules differ across Windows Command Prompt, PowerShell, Bash, Zsh, and other shells. Spaces split arguments unless the path is quoted. Ampersands, dollar signs, backticks, wildcard characters, parentheses, and semicolons may have special meanings.

mpv --sub-file="C:\Media Files\captions.en.srt" "C:\Media Files\movie.mkv"

On Linux or macOS, a comparable command is:

mpv --sub-file="/home/user/Media Files/captions.en.srt" "/home/user/Media Files/movie.mkv"

Do not copy escaping rules from one shell into another without checking them. Success means terminal output shows the intended file being opened, with no truncated path or stray argument.

3.2 Compare Direct Launches With Frontend Launches

Graphical frontends, file associations, media managers, and desktop launchers may not pass a command as a shell command. Some require each argument in a separate field. Others automatically add quotes, place options after filenames, use an older mpv executable, or insert a standalone --.

Run the known-good command directly in a terminal. Then inspect the frontend's generated command or debug log. Confirm its configured mpv executable by comparing paths and version output. If the direct command works, mpv itself is not the primary problem. Correct the frontend's argument format or executable path and stop changing mpv.conf.

3.3 Consider Per-File Option Scope and Ordering

Ordinary command-line options generally affect files according to mpv's option handling, but playlist and multi-file commands can also use per-file option markers. mpv supports file-local option blocks using --{ and --}. A setting inside such a block is intended for the relevant file rather than every subsequent item.

Misplaced braces, a frontend that reorders arguments, or options attached to the wrong playlist entry can make behavior seem inconsistent. Reduce the command to one file and one option. Once that works, add the per-file block and additional items carefully. Success means each option affects only its intended file.

3.4 Verify Permissions and Media Limitations

Confirm that mpv can read input files, external subtitles, shaders, scripts, cookies, and playlists, and can write logs or screenshots to the requested destination. Avoid running mpv as an administrator merely to hide a permissions problem. Correct ownership or choose a user-writable location instead.

High-bitrate media may expose storage, network, or decoder limits. If an option is recognized but playback still stutters, compare a local file with a network source and compare software with hardware decoding. This separates parsing from throughput or decode performance.

4. Use mpv Diagnostics Instead of Guessing

4.1 Read Terminal Output First

Terminal output often states the exact failure: unknown option, invalid value, file not found, failed audio device, unavailable video output, unsuccessful hardware decoder, or missing external program. Scroll to the earliest relevant error because later failures may be consequences.

An unknown-option message calls for spelling and manual checks. An invalid-value message means the option was recognized but its value was not. A filename-opening error involving the option text indicates tokenization, placement after --, malformed hyphens, or frontend argument handling.

4.2 Increase Logging Carefully

Use verbose message levels for a focused reproduction:

mpv --no-config --msg-level=all=v --log-file="mpv-test.log" --your-option=value "video.mkv"

Choose a writable log destination. Logs can include local paths, URLs, filenames, and other environment details, so review and redact them before sharing publicly. Search the log for the option name, the selected backend, and the first error. Success means the log confirms the option value or identifies the subsystem rejecting it.

4.3 Use Profiles, Stats, and Track Information

--show-profile=name helps audit profiles without activating unrelated changes. During playback, mpv's built-in statistics overlay can expose decoder, frame timing, dropped frames, video parameters, and rendering information. Default key bindings may be changed by input.conf, so consult the installed manual or your bindings if the expected stats key does nothing.

For subtitle, audio, and video selection issues, inspect the available track list and currently selected identifiers. For hardware decoding, verify the active decoder path rather than assuming that --hwdec=auto guarantees hardware use. Automatic modes may legitimately choose software when a suitable hardware path is unavailable.

5. Run a Clean Temporary Test Before Changing Multiple Settings

A controlled test prevents one fix from being hidden by another change. Use this sequence:

1. Open a terminal and confirm which mpv executable is running.
2. Choose one known local media file with a simple absolute path.
3. Run mpv with --no-config and one visible option.
4. Retype the option using --option=value syntax.
5. Keep every option before any standalone -- marker.
6. Add the original file, URL, track, script, shader, or backend requirement.
7. Restore the normal configuration and identify the first step that changes behavior.

Change only one variable per run. If the clean test succeeds, preserve the working command before restoring profiles and scripts. If it fails with an unknown option, check the documentation installed for the exact mpv executable you invoked. If the option is accepted but its result is unavailable, troubleshoot the associated media track, backend, external tool, or operating-system capability.

Stop changing settings when the terminal confirms the intended option and the requested behavior occurs. Additional speculative changes can create a second problem and make the original fix harder to verify.

6. Quick Fix Checklist

• Use two ASCII hyphens and prefer --option=value.
• Move intended options before the standalone -- marker.
• Quote paths and URLs according to the active shell.
• Test one local file with --no-config.
• Compare the direct terminal command with the frontend's generated arguments.
• Check whether a profile, script, binding, or watch-later state changes the property.
• Verify that requested subtitle, audio, or video tracks actually exist.
• Read the first relevant terminal error before changing drivers or backends.
• Use --msg-level=all=v and --log-file for a reproducible diagnostic log.
• Confirm paths, permissions, external tools, network access, and output capabilities.
• Add options back one at a time and stop when the working result is confirmed.

7. Frequently Asked Questions

7.1 Why Does mpv Treat My Option as a Filename?

The option may appear after a standalone --, begin with a non-ASCII dash, use malformed legacy syntax, or be passed as one incorrectly quoted argument by a frontend. Put it before --, retype it as --option=value, and test directly in a terminal.

7.2 Why Does an Option Work With --no-config but Not Normally?

A configuration file, profile, script, input binding, or saved state is changing the same property or related behavior. Restore components gradually and inspect named profiles with --show-profile=profile-name. Correct the specific conflict instead of deleting the whole configuration folder.

7.3 Does Option Order Matter in mpv?

It matters around the standalone end-of-options marker and in commands using per-file scopes. Frontends may also reorder arguments. Reduce the test to one file, put normal options before --, and add playlist or per-file syntax only after the basic command works.

7.4 Why Is --hwdec=auto Accepted but Hardware Decoding Is Not Used?

Acceptance only means the option was parsed. Automatic hardware decoding can fall back when the codec, profile, bit depth, driver, GPU API, or output path is incompatible. Review verbose terminal output or playback statistics to identify the decoder actually selected.

7.5 Why Does the Command Work in a Terminal but Fail in a GUI?

The GUI may use another mpv executable, a different working directory or PATH, or its own argument-quoting rules. It may also place arguments after --. Inspect the frontend's launch command and configure each argument in the format that frontend expects.

7.6 When Should I Reinstall mpv?

Reinstallation is rarely the first fix for a parsing symptom. First verify the executable path, modern option syntax, clean --no-config behavior, frontend arguments, and terminal errors. Consider reinstalling only when a trusted package is demonstrably damaged or the executable and its required files are incomplete.