mpv Cache Settings Not Working: How to Fix It

When mpv cache settings are not working, the problem is usually not solved by assigning an arbitrarily large cache. The more common causes are obsolete option names, a configuration file that is not being loaded, an option overridden by a profile or script, a cache limit that does not match the stream, or a bottleneck outside mpv. Online video extraction, server behavior, storage speed, decoding performance, and network stability can all resemble a cache failure.

The safest troubleshooting method is to test one known stream with a clean mpv command, verify that the installed build recognizes each option, and then reintroduce your normal configuration in small steps. This guide focuses specifically on cache behavior while showing how subtitles, tracks, hardware decoding, yt-dlp, shaders, HDR processing, and other customizations can affect the diagnosis.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by defining the symptom precisely. Cache settings may appear ineffective because playback still pauses, the statistics overlay shows less buffered data than expected, seeking remains slow, or an option copied from an older tutorial produces an error. Those symptoms have different causes.

Open PowerShell, Command Prompt, Terminal, or your usual shell and run mpv without its normal configuration:

mpv --no-config --cache=yes --demuxer-readahead-secs=30 --demuxer-max-bytes=150MiB "STREAM_URL"

Replace STREAM_URL with a legal, directly accessible stream you are authorized to play. On Windows, use the full path to mpv.exe if mpv is not on PATH. Shell quoting differs, so ordinary double quotes are the safest starting point for URLs containing ampersands, question marks, or other special characters.

This test deliberately excludes profiles, input bindings, scripts, shaders, and user configuration. It also uses demuxer cache controls rather than relying on option names found in old tutorials.

1.1 Compare the same source with and without caching

Run a second test against the same source:

mpv --no-config --cache=no "STREAM_URL"

Do not expect every stream to show a dramatic difference. A fast connection and a modest-bitrate video may play perfectly in both tests. Conversely, a live stream may expose only a limited window, so mpv cannot necessarily buffer minutes ahead regardless of the memory limit.

A successful cache test normally shows one or more of these results:

• Playback survives short network interruptions more reliably.
• The buffered duration or cache data shown by statistics increases.
• Forward seeking within already buffered media becomes more responsive.
• Terminal output no longer reports an unknown or invalid option.

If the clean command behaves correctly, stop changing global cache values. The cache mechanism works, and the fault is probably in your configuration, profile, script, command syntax, or source-specific behavior.

1.2 Separate network buffering from local-file performance

A local file usually does not benefit from a large network-style read-ahead cache. If a local high-bitrate video stutters, test storage throughput, decoding, shaders, HDR conversion, and video output before increasing cache memory.

Network streams are different because data arrives over a variable connection. Cache controls can absorb temporary delivery gaps, but they cannot repair sustained bandwidth that is lower than the media bitrate. If a 60 Mbps stream is delivered at 40 Mbps for its entire duration, buffering only postpones the interruption.

2. Check Which Cache Options Your mpv Build Actually Supports

mpv changes over time, and tutorials may describe options or semantics from another generation of the player. Instead of guessing, ask the installed executable what it supports:

mpv --list-options

Search the output for cache, demuxer-max-bytes, demuxer-max-back-bytes, and demuxer-readahead-secs. You can also consult the manual supplied for the build you are actually running.

2.1 Understand the main demuxer cache controls

• cache=yes: Explicitly enables the cache when appropriate for the test.
• demuxer-max-bytes: Limits the primary demuxer cache allocation. A larger value permits more buffered data but consumes more memory.
• demuxer-max-back-bytes: Controls how much cached data may be retained behind the current playback position, which can affect backward seeking.
• demuxer-readahead-secs: Requests a target amount of read-ahead measured in time, subject to byte limits and source behavior.

The time and memory limits interact. For example, 30 seconds of a very high-bitrate stream may require more memory than the configured byte ceiling permits. Increasing only demuxer-readahead-secs will not force mpv to exceed demuxer-max-bytes.

A practical configuration might look like this:

cache=yes
demuxer-readahead-secs=30
demuxer-max-bytes=150MiB
demuxer-max-back-bytes=50MiB

Treat these as test values, not universal recommendations. Low-memory systems and multiple simultaneous mpv instances may require smaller limits. Extremely high-bitrate network media may need more.

2.2 Avoid obsolete options copied from tutorials

If mpv reports that an option does not exist, remove it rather than trying different spellings from random forum posts. Confirm current syntax through --list-options and the official manual. An option may have been removed, replaced, deprecated, or changed in meaning.

Success means mpv starts without option-parsing errors and the active cache responds to the current demuxer controls. Once that happens, stop adding legacy cache options. Combining old and current controls makes future troubleshooting harder.

3. Verify the Config File, Profiles, Bindings, and Scripts

If --no-config works but normal playback does not, examine how your regular setup changes mpv. Do not delete the entire configuration folder. First test the specific files and features that can override playback behavior.

3.1 Confirm that mpv reads the intended configuration

Common user configuration locations include %APPDATA%\mpv\mpv.conf on Windows and ~/.config/mpv/mpv.conf on many Linux systems. macOS installations commonly use ~/.config/mpv/mpv.conf, although packaging and launch methods can affect paths.

Launch mpv from a terminal with verbose logging and inspect which configuration files it loads:

mpv -v "STREAM_URL"

Check for duplicate portable configurations, system-wide files, launcher-supplied arguments, and typographical errors. Configuration entries do not start with the command-line -- prefix. For example:

cache=yes
demuxer-readahead-secs=30

If your edited file is loaded and its options are accepted, the path is correct. If it never appears in the log, stop adjusting cache sizes and fix the configuration location or permissions first.

3.2 Inspect conditional and named profiles

A profile can override a global cache value for URLs, protocols, file types, or other conditions. Search mpv.conf for bracketed profile sections and cache-related lines. To inspect a named profile, use:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the actual profile name. Also inspect auto profiles or conditional profiles that may activate only for network streams.

Success means the final active values match your intention for the tested URL. When a profile contains the conflicting assignment, correct it there rather than duplicating another override later in the file.

3.3 Test input bindings and runtime property changes

An input.conf binding or script can change cache-related properties after startup. Search input.conf and the scripts directory for terms such as cache, demuxer, and readahead. Temporarily disable only the suspected binding or script, then repeat the test.

Scripts can also load alternate URLs, restart playback, select tracks, or modify options. Rename one suspected script temporarily or point mpv to an empty temporary script directory rather than removing every customization at once.

3.4 Rule out adjacent playback settings

Subtitle rendering, audio-track selection, screenshot settings, and IPC do not normally control the cache. However, scripts associated with these features may alter playback, and expensive processing may create stutter that resembles buffering.

Temporarily remove custom shaders, complex subtitle scripts, interpolation, heavy video filters, and automatic profile logic. Select a single known audio and video track. If the cache fills while playback still drops frames, the issue is probably rendering or decoding rather than buffering.

4. Check the Source, yt-dlp, Network, and System Bottlenecks

Cache behavior depends on whether mpv receives a direct media stream, a playlist, or a URL resolved by an external tool. It also depends on what the remote server permits.

4.1 Distinguish direct streams from yt-dlp extraction

For supported web pages, mpv may rely on yt-dlp to resolve the page into playable media URLs. If extraction fails, expires, selects an unsuitable format, or cannot find the external executable, changing cache limits will not fix the underlying problem.

Run mpv from a terminal and inspect the output for yt-dlp or hook errors. Confirm that a trusted installation of yt-dlp is accessible to mpv. If necessary, test yt-dlp separately against content you are authorized to access. Do not download replacement executables from random mirrors or attempt to bypass DRM.

A successful fix produces a valid media URL and begins demuxing. Only after that point is cache tuning relevant.

4.2 Consider server and stream limitations

Some live services expose only a short moving window. Other servers throttle requests, reject seeking, omit reliable duration information, or use segmented delivery. A playlist can also switch between segments or bitrates in ways that make cache statistics fluctuate.

Test a second known-good network source. If cache controls work there, the original source is limiting behavior. Stop increasing memory because the player cannot buffer data the server does not provide.

4.3 Check network access and shell quoting

A URL containing & may be interpreted by a shell if it is not quoted. Expiring query parameters can also make a copied media URL fail later. Use quotes, retest with a fresh URL, and check whether a firewall, VPN, proxy, DNS filter, or security tool blocks mpv while allowing a browser.

For a network share, distinguish a mounted file path from an HTTP stream. SMB, NFS, and cloud-mounted files can look local to mpv while still suffering network latency. Test by copying a short sample to local storage. Smooth local playback points to the share or network path rather than the demuxer cache configuration.

4.4 Separate decoding and output problems from cache problems

GPU drivers, hardware decoding, HDR tone mapping, display servers, audio backends, and output drivers can cause stalls or frame drops after data has already arrived. Compare playback with hardware decoding disabled:

mpv --no-config --hwdec=no "SOURCE"

Then test an appropriate hardware-decoding mode supported by your installation. Also try without custom shaders or filters. On Linux, terminal output may reveal Wayland, X11, Vulkan, OpenGL, or audio backend errors. On Windows and macOS, driver and output initialization messages can provide similar clues.

If statistics show healthy buffered data while dropped frames or audio underruns continue, stop tuning cache settings. Investigate decoding load, GPU compatibility, display timing, audio output, or media corruption instead.

5. Use Logs and Runtime Information to Identify the Real Failure

mpv provides enough diagnostic information to distinguish an ignored option from an empty cache or overloaded decoder. Capture evidence before making broad changes.

5.1 Create a focused log file

Run a clean test with a log:

mpv --no-config --log-file=mpv-cache-test.log --msg-level=all=v --cache=yes --demuxer-readahead-secs=30 --demuxer-max-bytes=150MiB "STREAM_URL"

Review the log for unknown options, failed URL access, demuxer errors, reconnects, yt-dlp failures, read errors, and decoder or output warnings. Logs can include local paths and URLs containing tokens, so remove sensitive information before sharing them publicly.

5.2 Read the statistics overlay correctly

mpv includes a statistics script in standard installations. The default key binding is commonly i for a temporary display and Shift+i for a persistent display, unless your bindings or frontend replace them.

The displayed cache amount may vary because mpv reads ahead, consumes data, prunes old data, and obeys both time and byte constraints. A configured maximum is a ceiling, not a promise that the cache will remain full. Fast local files may show little meaningful cache activity because there is no reason to accumulate a large network buffer.

Success does not require the overlay to equal the exact maximum. Success means buffering proceeds within the configured constraints and playback handles realistic short interruptions.

5.3 Inspect tracks and media characteristics

Use the track list in the user interface or terminal output to confirm which video, audio, and subtitle tracks are active. A high-resolution video track, lossless audio stream, image-based subtitles, or unexpectedly high-bitrate format can increase processing or bandwidth demands.

If selecting a lower-bitrate track resolves interruptions while the cache was already filling, available bandwidth was the constraint. If disabling a demanding subtitle or shader resolves frame drops with a healthy cache, rendering was the constraint.

6. Run a Clean Temporary Test Before Changing Multiple Options

Changing ten options at once can hide the cause and create new conflicts. Use a controlled sequence:

1. Choose one reproducible source and note whether it is local, direct HTTP, a playlist, or yt-dlp-resolved.
2. Run it with --no-config and no cache customization.
3. Enable cache=yes.
4. Add a moderate demuxer-readahead-secs value.
5. Add a compatible demuxer-max-bytes limit.
6. Observe statistics and terminal output for several minutes.
7. Re-enable your normal configuration.
8. Restore profiles, scripts, shaders, and hardware decoding one category at a time.

Use a temporary configuration file if you need a repeatable test:

mpv --no-config --include="PATH_TO_TEMP_CONF" "STREAM_URL"

The temporary file should contain only verified options. This approach leaves your working setup intact and makes each result attributable to a specific change.

Stop when the stream maintains a useful buffer, playback survives normal connection variation, and no cache-related errors appear. A larger value is not automatically better. Excessive caching increases memory use, can retain unnecessary data, and does not improve decoding speed.

7. Quick Fix Checklist

• Run the same source with --no-config to isolate customization.
• Confirm supported option names with mpv --list-options.
• Use current demuxer cache controls instead of blindly copying old tutorials.
• Balance demuxer-readahead-secs with a sufficient byte limit.
• Check that mpv loads the configuration file you edited.
• Inspect profiles for source-specific overrides.
• Search input bindings and scripts for runtime property changes.
• Quote URLs correctly in the current shell.
• Check yt-dlp output before treating extraction failures as cache failures.
• Test a second stream to identify server-specific limitations.
• Compare network media with a local copy when possible.
• Use the statistics overlay to distinguish an empty cache from dropped frames.
• Test without custom shaders, filters, subtitles, and hardware decoding.
• Capture a log with --log-file and focused message output.
• Stop increasing cache values once the actual bottleneck is elsewhere.

8. Frequently Asked Questions

8.1 Why did changing stream cache options make no visible difference?

The connection may already be fast enough, the stream may limit read-ahead, or the byte ceiling may prevent the requested number of seconds from being buffered. The source might also be a local file, where large network-oriented caching offers little benefit. Check the statistics overlay and compare clean runs before assuming the option was ignored.

8.2 How much memory should I assign to the mpv cache?

Use enough memory to hold the desired read-ahead for the stream bitrate, with reasonable headroom. For example, high-bitrate 4K media requires substantially more bytes per buffered second than compressed audio. Avoid assigning huge limits by default, especially on low-memory systems or when running several players. Increase the limit gradually and stop when additional memory no longer improves resilience.

8.3 Why does the cache shown in statistics stay below the configured maximum?

The maximum is a limit, not a target. mpv may be constrained by the read-ahead time, server delivery rate, live window, demuxer behavior, or current playback position. It also consumes and discards data during playback. A fluctuating value is normal if playback remains stable.

8.4 Can cache settings fix stuttering local HDR or high-bitrate video?

Only when storage delivery is the bottleneck. If the file is already read fast enough, stuttering is more likely related to decoding, HDR processing, shaders, GPU drivers, display synchronization, or audio output. Confirm that buffered data is available, then test without hardware decoding, custom shaders, and filters to isolate the rendering path.

8.5 Why does an option from an old mpv guide produce an error?

The guide may describe an obsolete, renamed, or differently interpreted option. Use mpv --list-options and the official manual for your installed build. Remove unsupported entries rather than stacking additional compatibility guesses into mpv.conf.

8.6 When should I stop troubleshooting cache settings?

Stop when a clean test buffers normally, the log shows accepted options, and the statistics overlay confirms data is available. If playback still fails while the cache remains healthy, move to the demonstrated bottleneck, such as network bandwidth, server restrictions, yt-dlp extraction, decoding load, GPU output, audio underruns, or a damaged media file. Continuing to enlarge the cache at that point will not fix the mpv player issue.