mpv Subtitle Download Script Not Working: How to Fix It

When an mpv subtitle download script stops working, the visible symptom is often simple: you press a shortcut, but no subtitle appears. The underlying cause may be an unloaded Lua script, an incorrect installation directory, a conflicting input binding, a misnamed script options file, a missing external program, or a subtitle provider rejecting the request. Network restrictions and API changes can also break a script even when mpv itself is working normally. The safest approach is to separate these possibilities, test one layer at a time, and stop as soon as the failed layer is identified.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by determining whether mpv can load the subtitle downloader script independently of your normal configuration. This prevents profiles, shaders, HDR settings, hardware decoding, yt-dlp options, and unrelated user scripts from obscuring the actual error.

Open Command Prompt, PowerShell, or a terminal and run mpv with no normal configuration while explicitly loading the subtitle script:

mpv --no-config --script=/full/path/to/subtitle-script.lua /path/to/test-video.mkv

On Windows, quote paths containing spaces:

mpv.exe --no-config --script="C:\Users\YourName\Downloads\subtitle-script.lua" "C:\Videos\test-video.mkv"

On Linux or macOS, use quotes when needed:

mpv --no-config --script="$HOME/.config/mpv/scripts/subtitle-script.lua" "$HOME/Videos/test-video.mkv"

Use a local video with a straightforward filename for this first test. Avoid an online URL, playlist, network share, HDR-specific profile, or unusual container until basic script loading has been verified.

1.1 What the minimal test establishes

This test answers one important question: can your installed mpv build load and execute the script without help from the rest of your configuration?

• If the script reports that it loaded and its shortcut responds, the normal configuration probably contains a conflict.
• If mpv reports a Lua syntax error or missing module, the script or one of its dependencies is the problem.
• If the script loads but subtitle searches fail, investigate the provider, network, API, and media identification layers.
• If mpv does not mention the script at all, verify its path, extension, and installation location.

Success at this stage means the script's command, menu, or key binding becomes available. It does not necessarily mean the remote subtitle provider is working. Once script loading succeeds, stop changing mpv playback options and test the provider separately.

2. Verify the Script Installation and Configuration

mpv automatically loads user scripts from the scripts directory inside its configuration directory. A frequent cause of an mpv subtitle download script not working is placing the Lua file beside the mpv executable, inside script-opts, or in a configuration directory that the current mpv installation does not use.

2.1 Check the script installation directory

Common user locations include:

• Linux: ~/.config/mpv/scripts/
• macOS: commonly ~/.config/mpv/scripts/, depending on how mpv was installed and launched
• Windows: commonly %APPDATA%\mpv\scripts\

Portable Windows builds may use a portable configuration directory associated with the executable. Package managers and graphical mpv front ends can also launch a different mpv binary or use another configuration location. If uncertain, run the exact mpv executable from a terminal and inspect its startup output rather than assuming that two shortcuts use the same installation.

The main script should normally have a .lua extension. Ensure it was not saved as script.lua.txt. On Windows, enable file-name extensions in File Explorer before checking.

Success means mpv's terminal output identifies the script during startup. Once that message appears without an immediate Lua error, do not move the script among additional folders.

2.2 Confirm Lua scripting is available

Subtitle downloader scripts are commonly written in Lua. A script cannot run if the mpv build lacks the required scripting support or was packaged unusually.

Run the explicit --script test from the previous section. If mpv recognizes the option but reports that Lua support or the Lua backend is unavailable, use a reputable mpv package from the official project guidance or your operating system's established package manager. Do not install a codec pack or download unrelated DLL files. Codec packs do not add Lua scripting support and can introduce new conflicts.

If another known working Lua script loads successfully, Lua support is present. At that point, the subtitle script itself, its dependencies, or its provider integration deserves attention.

2.3 Check the script options filename

Many scripts read settings from a file in the script-opts directory, not from the scripts directory. The usual layout resembles:

mpv/
  mpv.conf
  input.conf
  scripts/
    subtitle-script.lua
  script-opts/
    subtitle-script.conf

The required options filename is determined by the script and may not match the repository name or downloaded ZIP filename. Read the script's documentation for the exact name. Renaming example.lua does not guarantee that example.conf is the expected options file.

Check every option for unsupported comments, incorrect separators, accidental quotation marks, and obsolete provider credentials. A typical mpv script options file uses one key=value setting per line, but the script's own documentation remains authoritative.

Temporarily move only the relevant options file out of script-opts, then test the script with defaults. Do not delete the entire mpv configuration folder. If the defaults work, restore settings one at a time. Success means the script loads and reaches its normal search action with either default or corrected options.

2.4 Inspect the input binding

The script may load correctly while its shortcut is overridden by input.conf, another script, or a profile. Confirm the command name documented by the script, including capitalization and punctuation.

Look in input.conf for duplicate assignments to the same key. A binding often resembles:

b script-binding subtitle-script/search

The exact binding name varies. Do not copy the example unless it matches the script documentation. Some scripts define a default key, while others require a manual binding.

To distinguish a key conflict from a script failure, invoke the documented script binding through mpv's console if available, or create a temporary binding on an unused key. If the temporary key works, the downloader is healthy and only the original binding needs correction.

3. Separate Script Loading From Subtitle Provider Failures

A script can load perfectly and still fail to download subtitles. Most downloaders communicate with an external website or API, and that service has requirements outside mpv's control.

3.1 Recognize a provider-side failure

Messages involving HTTP status codes, authentication, rate limits, JSON parsing, TLS, DNS, or empty search results generally indicate that execution reached the network stage. Examples include unauthorized requests, forbidden requests, too many requests, connection timeouts, and responses the script can no longer parse.

Check the script's official project page for current setup instructions and open issues. Providers may change API endpoints, require an account, introduce API keys, alter response formats, or block older clients. A script that has not been updated for the provider's current API may need a maintained release.

Never enter credentials into a modified script obtained from an unknown mirror. Use the script's official repository or a trusted package source, and review where credentials are stored.

3.2 Test network access without changing playback settings

If logs show a connection failure, confirm that the computer can reach the provider using a normal browser or the external command documented by the script. Corporate proxies, DNS filters, firewalls, VPN routes, and regional service restrictions can affect API requests.

Some subtitle scripts call external tools such as curl, wget, Python, or another downloader. Verify the precise dependency documented by your script:

curl --version
python --version
python3 --version

Only test tools the script actually requires. If the command works in your terminal but not when mpv is launched from a desktop shortcut, the graphical session may have a different PATH. Configure an absolute executable path if the script supports one, or correct the environment used to launch mpv.

Success means the log advances beyond process creation and network connection into a valid subtitle search response. At that point, stop modifying firewall, PATH, and dependency settings.

3.3 Check whether the media can be identified

Subtitle services often search using a filename, title, season and episode number, release metadata, or file hash. A generic filename such as video.mkv may produce no results even though the script and provider are operational.

Test with a legally obtained local file whose filename clearly includes the title and, for television content, a conventional season and episode identifier. Online streams, temporary URLs, stdin input, and some network sources may not provide a stable local path or hash. If local-file searches work but URL searches do not, the limitation is media identification rather than general mpv failure.

4. Use mpv Logs to Identify the Failed Layer

Terminal output is the fastest way to avoid blind configuration changes. Launch mpv from a shell instead of double-clicking it, reproduce the failure once, and read the messages immediately surrounding the script's name.

4.1 Increase message detail

Use a targeted message level and write the results to a file:

mpv --msg-level=all=v --log-file=mpv-subtitle-test.log /path/to/test-video.mkv

For a cleaner isolation test, combine logging with explicit script loading:

mpv --no-config --script=/full/path/to/subtitle-script.lua --msg-level=all=v --log-file=mpv-subtitle-test.log /path/to/test-video.mkv

Reproduce the problem once, close mpv, and search the log for the script filename, lua, error, failed, HTTP, or the external tool's name. Logs may contain local paths, URLs, usernames, tokens, or API credentials. Redact sensitive information before sharing them publicly.

4.2 Interpret common log patterns

• No script loading message: the path, file extension, configuration directory, or selected mpv binary is wrong.
• Lua parse error: the script may be incomplete, corrupted, or incompatible with its expected environment.
• Missing module or executable: install or correctly reference the dependency named by the script documentation.
• Unknown script option: remove or update an obsolete setting in the script's options file.
• Binding not found: correct the command name in input.conf.
• HTTP or API error: investigate credentials, rate limits, provider availability, and script maintenance.
• Download succeeds but subtitle does not appear: inspect subtitle loading, format, destination path, and track selection.

4.3 Use profiles and overlays only when relevant

If the script works with --no-config but fails normally, inspect active profiles and profile-specific script options. The command-line option --show-profile=NAME can display the contents of a named profile. Review automatic profiles in mpv.conf for settings that apply only to certain protocols, file extensions, or display conditions.

The stats overlay and track list are useful after a subtitle has been downloaded. They can show whether mpv loaded a subtitle track and which track is selected. They do not diagnose an API request that never completed.

Likewise, GPU drivers, display servers, video output drivers, HDR configuration, hardware decoding, and audio backends rarely cause a subtitle downloader's network request to fail. Investigate those components only if mpv itself crashes, video output disappears, or the log explicitly identifies that subsystem.

5. Check Download Paths, Permissions, and Subtitle Selection

A downloader may find a subtitle but fail while writing it to disk. This is especially common with read-only directories, removable drives, network shares, sandboxed applications, and protected Windows folders.

5.1 Test a writable local directory

Copy a test video to a user-owned local folder and try again. Avoid system directories and locations requiring administrator privileges. Do not run mpv as administrator merely to bypass a permissions problem. Correct the destination or folder permissions instead.

If the script supports a configurable download directory, use a simple absolute path. Verify that the directory already exists if the script does not create it automatically. Paths containing spaces require careful quoting when supplied through a shell, although quotes may not belong inside a key=value options file unless its documentation says so.

Success means a subtitle file appears in the intended location and the log contains no write or permission error.

5.2 Confirm mpv loads the downloaded subtitle

If the file downloads but is not visible, drag the subtitle file onto the mpv window or load it explicitly:

mpv /path/to/video.mkv --sub-file=/path/to/subtitle.srt

Open mpv's track list and select the downloaded subtitle track. Check whether subtitles were intentionally disabled or whether a language preference selected another track. A subtitle delay, forced-subtitle preference, or styling option can also make a successfully loaded track appear absent or mistimed.

If explicit --sub-file loading works, mpv's subtitle renderer is functioning. Return to the script's save-and-load behavior rather than changing video output or hardware decoding.

6. Run a Clean Temporary Test Before Editing More Settings

Once logs suggest a configuration conflict, create a temporary test environment rather than rewriting your working setup. Preserve your existing files and change only one variable per test.

1. Choose a small local video in a writable directory.
2. Run mpv with --no-config.
3. Load only the subtitle downloader through --script.
4. Use the script's default configuration first.
5. Confirm that its binding or command responds.
6. Check whether the provider search starts.
7. Confirm that a result downloads and becomes a selectable subtitle track.
8. Restore the script options file, then your input binding, then other scripts.

If failure begins immediately after one component is restored, that component is the likely cause. Compare its contents with the script's current documentation rather than replacing unrelated mpv settings.

Do not test several changes simultaneously. Updating the script, replacing mpv, changing DNS, editing bindings, and rewriting options at once may hide the original cause and make future troubleshooting harder.

7. Quick Fix Checklist

• Confirm the script is a real .lua file in mpv's active scripts directory.
• Run --no-config --script=/full/path/script.lua with a simple local video.
• Read terminal output for a script-loading message or Lua error.
• Verify the exact script-opts filename required by the script.
• Temporarily test without the script's options file.
• Check input.conf for duplicate keys and incorrect script-binding names.
• Verify only the external tools specifically required by the script.
• Check API credentials, provider status, rate limits, and maintained script releases.
• Test a descriptive local filename instead of an online or temporary stream URL.
• Use a writable local download directory.
• Load the downloaded subtitle manually to test mpv's subtitle renderer.
• Restore configuration components one at a time and stop when the failure returns.

8. Frequently Asked Questions

8.1 Why does the script work with --no-config but not normally?

Your normal configuration likely introduces a conflicting key binding, obsolete script option, automatic profile, or another user script. Restore each component individually. The first restored component that causes the failure is where you should focus.

8.2 How do I know whether mpv loaded the Lua script?

Launch mpv from a terminal with verbose logging and search for the script filename. A successful load has no immediate Lua parse, missing-module, or initialization error. You can also test the script's documented binding. A provider returning no results is not proof that the script failed to load.

8.3 Why does the downloader find subtitles but fail to save them?

The destination may be read-only, missing, sandbox-restricted, or incorrectly quoted. Test with a local video in a user-owned folder and configure a simple writable destination. Avoid solving this by running mpv with elevated privileges.

8.4 Can hardware decoding or HDR settings break subtitle downloading?

Normally, no. Hardware decoding, GPU drivers, HDR profiles, shaders, and video output settings affect playback or rendering, not the downloader's API request. Consider them only when mpv crashes, subtitle rendering fails after a successful download, or logs explicitly point to the video subsystem.

8.5 Why does the script work with local files but not online URLs?

The provider may require a stable filename, file hash, or episode metadata that an online URL does not expose. yt-dlp can also produce temporary media URLs with limited identifying information. This is usually a media-identification limitation, not a general mpv player issue.

8.6 Should I reinstall mpv or delete its configuration?

Not initially. An explicit --no-config --script=... test provides the same isolation without destroying working profiles, shaders, bindings, and playback settings. Reinstall only when logs indicate a damaged or unsuitable mpv build, and preserve your configuration before making package changes.