mpv Mpv.conf Syntax Error: How to Fix It

An mpv mpv.conf syntax error usually appears as an unknown option, invalid parameter, parsing failure, profile error, or warning printed when mpv starts. Sometimes mpv still opens but silently ignores the affected setting. In other cases, playback, subtitles, hardware decoding, HDR output, screenshots, scripts, online video, or input bindings stop working.

The most common causes are command-line syntax copied directly into a configuration file, incorrect separators in list options, improperly quoted paths, obsolete option names, malformed profiles, or settings placed in the wrong file. The safest troubleshooting method is to confirm that mpv works without configuration, identify the exact warning, isolate the responsible line, and stop changing settings as soon as a clean test succeeds.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing anything, verify whether the problem actually comes from mpv.conf. Run mpv from a terminal with configuration loading disabled and open a known-good local media file.

On Windows, open PowerShell or Command Prompt in the directory containing mpv.exe, or use its full path:

mpv.exe --no-config "C:\Media\test.mp4"

On Linux or macOS, use:

mpv --no-config "/path/to/test.mp4"

Choose a short, ordinary file that has played successfully before. Do not begin with an HDR file, network stream, unusually encoded video, or playlist because those introduce unrelated variables.

If the file plays with --no-config but fails during a normal launch, the configuration, a profile, a script, or another user-loaded component is probably responsible. If the clean command also fails, the issue may instead involve the file, mpv installation, permissions, output driver, GPU, audio system, or operating system.

Success means the test file opens, video and audio work, and the terminal does not report the original configuration warning. At that point, stop investigating codecs or reinstalling software. You have already narrowed the problem to something loaded by the normal configuration.

1.1 Find the active configuration location

Make sure you are editing the configuration file that your mpv installation actually reads. A portable Windows build can use a portable configuration directory, while a standard installation may use the current user's application-data location. Linux commonly uses the user's mpv directory under the XDG configuration location, and macOS commonly uses the user's configuration directory.

Run the following command to ask mpv for its configuration directory:

mpv --no-config --show-config-path

Depending on the build and command context, the displayed path helps identify where mpv expects user configuration. Also check terminal startup output for the configuration file being loaded. Avoid editing multiple copies of mpv.conf because that makes every test ambiguous.

2. Check the Setting Directly Related to the Failure

Read the first relevant warning printed in the terminal. Later errors may be consequences of the first malformed option. Search mpv.conf for the option named in that warning and inspect nearby lines for syntax problems.

2.1 Use option=value syntax without leading dashes

Command-line options normally begin with two dashes, but options in mpv.conf do not. A command-line setting such as:

mpv --hwdec=auto --sub-auto=fuzzy video.mkv

should appear in mpv.conf as:

hwdec=auto
sub-auto=fuzzy

Do not write --hwdec=auto in mpv.conf. Also avoid placing a media filename after an option as if the file were a shell command. Configuration files contain settings, not a complete mpv invocation.

Although some boolean options support forms that omit an explicit value, option=value is usually the clearest format for troubleshooting. Use one setting per line until the error has been isolated.

Success means the unknown-option or parsing warning disappears and the intended behavior occurs. Once that happens, stop rewriting unrelated settings.

2.2 Check comments and whitespace

A comment begins with #. Put comments on their own lines while diagnosing a syntax problem:

# Enable automatic hardware decoding
hwdec=auto

Normal whitespace around an assignment is often accepted, but a simple name=value layout removes doubt. Watch for invisible characters introduced by rich-text editors, copied web pages, smart quotation marks, or an unusual file encoding. Use a plain-text editor and save the file as normal UTF-8 text.

A leading # disables the entire setting. If the warning disappears only after commenting out a line, that line is the current suspect. The absence of the warning confirms isolation, not necessarily that the option itself is invalid. Its value or formatting may still be the actual cause.

2.3 Verify list-option separators

Some mpv options accept lists. Their required separator and escaping rules depend on the option. A value copied from a shell command may use quoting or escaping that does not translate directly into mpv.conf.

Do not assume commas, semicolons, or colons are interchangeable. Colons can also appear inside Windows drive paths, URLs, and filter syntax. Consult the option's entry in the mpv manual and begin with one list item. Add the remaining items individually after the first item works.

For options supporting append operations, mpv may provide an -append form. Use only the operation documented for that option. Success means every expected list item appears or takes effect without an invalid-value warning.

2.4 Quote paths carefully

Paths containing spaces, commas, colons, backslashes, or quotation marks deserve special attention. In mpv.conf, assign the path as the option's value rather than copying an entire shell command. For example:

screenshot-directory="C:\Users\Name\Pictures\mpv shots"

On Linux or macOS, a comparable setting could be:

screenshot-directory="/home/name/Pictures/mpv shots"

Shell quoting and configuration-file quoting are separate concepts. A path that works in PowerShell, Bash, or Zsh is not proof that the same surrounding syntax belongs in mpv.conf. Test a simple path without spaces if uncertainty remains, then restore the intended path after the option works.

Success for a screenshot setting means mpv creates the screenshot in the selected directory and prints no write or parsing error. Stop changing screenshot format or template settings once that happens.

2.5 Check deprecated or renamed options

An older guide, dotfile repository, or forum answer may use an option that your installed mpv no longer recognizes. Do not guess a replacement based only on a similar name. Search the current mpv manual or run:

mpv --list-options

You can filter the output with an operating-system search tool, or save it to a text file for inspection. If an option is absent, remove or comment out that line and consult current documentation for the supported equivalent.

Success means mpv starts without the unknown-option warning. If the removed setting controlled an optional enhancement, confirm normal playback first before trying to reproduce that enhancement with a current option.

2.6 Validate profiles and input bindings separately

Profiles in mpv.conf use section headers such as [profile-name]. A misspelled header, malformed conditional profile, or invalid option inside a profile may cause errors only when that profile becomes active.

Inspect a profile with:

mpv --show-profile=profile-name

For input.conf, do not use mpv.conf assignment syntax. An input binding normally begins with a key followed by an mpv command. Keep configuration options in mpv.conf and key bindings in input.conf. If a key does nothing, launch mpv from a terminal and press it while watching for command or binding errors.

Success means the profile displays the expected options or the assigned key performs the intended action without an input-command error.

3. Separate Syntax Errors From Playback and System Problems

A valid configuration line can still fail because the referenced resource or subsystem is unavailable. Once syntax warnings are gone, evaluate only the component named by the remaining error.

3.1 Hardware decoding, HDR, and output drivers

A setting such as hwdec=auto may be syntactically correct even when the GPU driver or selected decoding API cannot handle a particular codec. Likewise, HDR behavior depends on the operating system, display path, output driver, GPU capabilities, and media metadata.

Test the same file with hardware decoding disabled from the command line:

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

If software decoding works, the original issue is not an mpv.conf syntax error. It is a hardware-decoding or driver compatibility problem. Keep the working software-decoding test as a baseline and investigate the documented hardware path for your platform.

Do not install random codec packs. mpv normally relies on its own multimedia stack, and an untrusted codec bundle is unlikely to repair malformed configuration syntax.

3.2 Audio backends and track selections

Options selecting an audio driver, device, or track can be valid but unsuitable for the current machine or file. First test without the relevant override. During playback, inspect available tracks using mpv's track list and cycle audio tracks if necessary.

A fixed audio track ID may not exist in every file. Prefer language or automatic selection rules when the collection varies, and confirm the actual tracks before declaring mpv broken. Success means the intended audio track plays without a device initialization error.

3.3 Subtitles, scripts, shaders, and external files

Subtitle paths, shader paths, script directories, and external audio files can fail because the file does not exist, is unreadable, or uses a path that was parsed incorrectly. Confirm the resource exists and test it explicitly with a clean command.

Temporarily disable the single script or shader associated with the failure rather than deleting the entire configuration folder. Third-party scripts can also have their own configuration syntax and runtime requirements. Their errors should not automatically be treated as mpv.conf errors.

Success means the external resource loads and appears in terminal output or produces its intended effect. If playback works without a third-party component, keep that component disabled until its documentation can be checked.

3.4 yt-dlp, URLs, playlists, and network streams

An online URL failure can result from unavailable yt-dlp, an incorrect executable path, site changes, authentication requirements, expired stream URLs, TLS problems, or network restrictions. First confirm local playback. Then test the URL from a terminal with --no-config.

If mpv reports that an external downloader cannot be found, verify that the trusted, official executable is installed and accessible through the system path or a correctly quoted mpv setting. Do not download replacement binaries from random mirrors.

A syntactically valid stream URL can still be offline or unsupported. Success means mpv resolves the URL, identifies tracks, and begins playback. If one site or stream fails while others work, stop modifying global video and audio options.

3.5 Permissions and writable directories

Configuration syntax cannot grant access to protected files or directories. Confirm that the current user can read media and external subtitle files and can write to screenshot, cache, and log destinations. On macOS, privacy controls may restrict access to certain folders. On Linux, sandboxed packages may have narrower filesystem access. On Windows, protected directories can reject writes by standard users.

Use a user-owned temporary directory to test screenshots or logs. If it works there, correct the destination's permissions or choose an accessible location rather than running mpv with unnecessary elevated privileges.

4. Use mpv Diagnostic Output to Find the Exact Line

Terminal output is the fastest way to distinguish an invalid option from a runtime failure. Start mpv from a terminal instead of opening the media file through a graphical file manager.

4.1 Increase message detail and save a log

Use a log file for a reproducible test:

mpv --log-file=mpv-test.log "test.mp4"

You can increase general verbosity with:

mpv --msg-level=all=v "test.mp4"

Higher verbosity creates substantial output, so reproduce the issue once and then search the log for terms such as error, failed, unknown, invalid, or the name of the suspect option. Focus on the earliest relevant warning.

Do not publish logs without reviewing them. They may contain local usernames, file paths, URLs, or tokens.

4.2 Compare normal and no-config runs

Create two logs using the same file, one with the normal configuration and one with --no-config. If only the normal run contains the syntax warning, inspect user configuration, profiles, scripts, and bindings. If both runs contain the same decoder or output error, the configuration is probably not the root cause.

4.3 Use the stats overlay and track list appropriately

The stats overlay can confirm the active video output, decoder, hardware-decoding status, frame timing, and other playback information. It is useful after mpv starts, but it does not replace startup logs for a parser error.

The track list helps verify whether a requested subtitle, audio, or video track actually exists. If a configured track ID is missing, change the selection rule rather than continuing to edit unrelated rendering options.

5. Run a Clean Temporary Test Before Changing Many Options

Once --no-config works, create a temporary minimal configuration containing only the suspect option. This is safer than deleting or renaming an entire configuration directory because it preserves scripts, bindings, profiles, and known-good settings.

A disciplined test sequence is:

1. Back up the specific file you plan to edit, such as mpv.conf or input.conf.
2. Comment out the suspect line in the active configuration.
3. Run the same known-good media file and check terminal output.
4. Add a minimal documented form of the option.
5. Test again before adding paths, lists, filters, or conditional profiles.
6. Restore related settings one at a time.

You can also use command-line options to test a corrected value without committing it to mpv.conf. Remember to include leading -- on the command line and omit them inside mpv.conf.

Stop changing settings as soon as the warning disappears and the intended feature works. Save the working configuration before attempting optional refinements. Changing ten options after reaching a working state makes future mpv troubleshooting much harder.

6. Quick Fix Checklist

• Run a known-good local file with mpv --no-config.
• Open mpv from a terminal and read the first relevant warning.
• Use option=value in mpv.conf without leading --.
• Keep mpv options in mpv.conf and key bindings in input.conf.
• Put comments on separate lines while troubleshooting.
• Use plain-text quotation marks and a plain-text editor.
• Verify separators against the manual for each list option.
• Quote paths carefully and test a simpler path when necessary.
• Check option availability with mpv --list-options.
• Inspect named profiles with --show-profile.
• Test scripts, shaders, subtitles, and external tools separately.
• Compare normal and --no-config log output.
• Restore settings one at a time and stop when the feature works.

7. Frequently Asked Questions

7.1 Why does an option work in the terminal but fail in mpv.conf?

The command line and mpv.conf use different outer syntax. On the command line, write --option=value. In mpv.conf, write option=value without the two leading dashes. Shell-specific quotation or escaping may also need to be removed or adapted.

7.2 Can one bad line prevent all mpv settings from loading?

A malformed line may be rejected while other settings continue loading, but its effects vary with the option and where it appears. A broken profile or complex value can also produce follow-on errors. Read the terminal output instead of assuming the entire file was ignored.

7.3 How do I identify an obsolete mpv option?

Compare the option with the current mpv manual and check mpv --list-options. If the name is not recognized, comment it out. Do not invent a replacement. Confirm clean playback first, then locate a documented modern equivalent if the feature is still required.

7.4 Should I delete my entire mpv configuration folder?

No. Begin with --no-config, then disable or correct the specific suspect line, profile, script, or binding. Deleting everything can erase working scripts, shader settings, input bindings, and profiles without showing which component caused the error.

7.5 Why does mpv.conf parse correctly but the feature still fail?

Correct syntax only means mpv understood the setting. The selected GPU API, audio device, file path, external program, network resource, track ID, or output directory may still be unavailable. Follow the component-specific error and test the simplest known-good resource.

7.6 What proves the mpv.conf syntax error is fixed?

The original parser or unknown-option warning no longer appears, the intended setting is visible or functional, and the same test file works during a normal launch. Once those conditions are met, stop editing unrelated options and preserve the working file.