mpv libarchive Support Missing: How to Fix It

When mpv reports that libarchive support is missing, refuses an archive:// URL, or cannot open media or subtitles stored inside a compressed archive, the problem is usually not a decoder, GPU, HDR, or codec issue. The most likely causes are an mpv build compiled without libarchive, an operating-system package with different optional features, incorrect archive URL syntax, shell quoting, a script generating an invalid path, or an archive format that the installed library cannot read.

The fastest approach is to test mpv without your normal configuration, confirm whether the archive protocol exists, and inspect terminal output before changing unrelated playback settings. This guide walks through that process on Windows, Linux, and macOS. It also explains a safe workaround: extract the required files and play them normally.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by separating archive support from the rest of your mpv setup. A clean test avoids user configuration files, scripts, shaders, profiles, input bindings, and automatic options that can obscure the original error.

1.1 Verify the mpv executable being used

Open Command Prompt, PowerShell, Terminal, or your preferred shell and run:

mpv --version

This confirms that the shell can find mpv and identifies the executable or package you are testing. If the command is not found, the immediate problem is your installation or PATH, not libarchive. On systems with multiple mpv installations, check which executable resolves first:

• Windows Command Prompt: where mpv
• PowerShell: Get-Command mpv
• Linux and macOS: command -v mpv

If your terminal and graphical launcher use different executables, they can have different build features. Continue testing the exact executable that displays the failure.

1.2 Check whether the archive protocol is available

Run the protocol listing and search for an archive-related entry. On Linux or macOS, use:

mpv --list-protocols | grep -i archive

In Windows Command Prompt, use:

mpv --list-protocols | findstr /i archive

In PowerShell, use:

mpv --list-protocols | Select-String archive

If the installed build exposes the archive protocol, the output should include an archive-related protocol. If no such entry appears, that is strong evidence that this particular executable does not provide libarchive-backed archive access. Protocol names and displayed build details can vary, so logs remain the final practical check.

1.3 Test a known local archive without configuration

Create or choose a small, nonencrypted archive containing a known playable media file or subtitle. Avoid testing first with a damaged archive, password-protected archive, network share, unusually long path, or format you have never opened elsewhere.

Use --no-config and quote the entire archive URL. The separator used in an archive URL can otherwise be interpreted by the shell, especially on Windows. A representative test is:

mpv --no-config "archive:///absolute/path/to/test.zip|sample.mkv"

Adjust the path and member name for your system. Archive URL details can differ by path style and mpv behavior, so consult the protocol documentation supplied with your build if the syntax is rejected. The critical points are to use the real internal member name, preserve case on case-sensitive systems, and quote the complete argument.

Success means mpv opens the member from the archive and begins normal demuxing or playback. At that point, stop changing installation packages. Your build has working archive support, and the fault is more likely the original path, archive, shell command, script, or configuration.

2. Check the mpv Setting or Customization Directly Related to the Failure

libarchive is a build-time dependency. An option in mpv.conf cannot add it to an executable that was compiled without it. Configuration troubleshooting is useful only after archive support is present, or when a script, profile, or binding changes the path being opened.

2.1 Test without configuration before editing files

Run the failing target with:

mpv --no-config "your-archive-url-or-file"

If it works, the executable supports the operation and something in your normal setup is interfering. Do not delete your entire configuration folder. Instead, inspect relevant entries in mpv.conf, input.conf, script options, and profile blocks.

Pay special attention to options that change file discovery, playlist interpretation, subtitle loading, or paths. Examples include custom sub-file-paths, explicit subtitle files, playlist settings, and scripts that rewrite filenames or construct archive:// URLs.

2.2 Inspect profiles and input bindings

A profile can apply options only to certain file types or paths, making the problem appear inconsistent. To print a named profile, run:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile referenced in your configuration or command. Review conditional profiles that match protocols, extensions, or directories.

Also inspect input.conf if the error occurs only after pressing a key. A binding may call loadfile, invoke a script message, or pass a path with broken escaping. Try opening the same target directly from the terminal. If direct opening succeeds, the binding or script command needs correction.

2.3 Separate archive access from playback options

Subtitle selection, audio and video track options, output drivers, hardware decoding, HDR settings, shaders, and screenshot settings operate after or alongside file opening. They do not enable libarchive. Options such as --hwdec, --vo, --ao, --sid, --aid, or --vid should not be changed merely because mpv cannot open an archive member.

If logs show that the archived file opened successfully but video output, audio output, or track selection failed afterward, you have passed the libarchive stage. Troubleshoot that later failure separately. Success at this stage looks like a log that identifies and opens the internal file, even if a decoder or output error follows.

2.4 Check scripts and external tools

A Lua or JavaScript extension may expect archive support even when the base player was built without it. Temporarily disable scripts with a clean --no-config test rather than deleting them. If the clean command works but the normal launch fails, re-enable scripts one at a time or review the script's documented requirements.

yt-dlp generally handles supported online URLs before passing media streams to mpv. Replacing yt-dlp will not add libarchive support. Check the yt-dlp path only when the terminal output explicitly says that yt-dlp cannot be found or an online URL cannot be resolved. Do not mix that separate failure with a local archive:// error.

3. Check the Operating System, Package, Path, and Archive

Not every mpv package includes every optional library. Two installations reporting similar mpv versions can still differ because they were produced by different maintainers with different build dependencies and feature choices.

3.1 Windows package differences

On Windows, determine where your build came from and whether its distributor documents libarchive support. Avoid random executable mirrors and codec packs. Codec packs do not supply a missing compile-time mpv feature and can introduce unrelated filters or security risks.

If the protocol test shows no archive support, replace mpv only with a current build from a reputable source linked by the mpv project or build it yourself with the required dependency. After installation, run where mpv again. Windows may still launch an older copy earlier in PATH.

Success means the intended executable appears first, --list-protocols shows archive support where applicable, and the same minimal test opens the archive member.

3.2 Linux package differences

Linux distributions choose their own build flags and dependencies. Minimal, containerized, third-party, or locally compiled packages may omit optional functionality. Use your distribution's package manager to inspect the installed package and available variants. Prefer an official distribution package unless you have a specific reason to compile mpv.

If you compiled mpv yourself, installing libarchive after compilation is not enough. The dependency must be detected during configuration, and mpv must then be rebuilt and reinstalled. Read the build configuration output rather than assuming detection succeeded.

After changing packages, verify the resolved executable with command -v mpv. Also check aliases, shell hashes, containers, Flatpak permissions, and sandbox boundaries if terminal and desktop behavior differ.

3.3 macOS package differences

On macOS, a package-manager installation, application bundle, and manually installed command-line binary can coexist. Determine which one Terminal runs and which one Finder or another launcher opens. A graphical app bundle may not be the same build as /opt/homebrew/bin/mpv, /usr/local/bin/mpv, or another PATH entry.

If rebuilding, ensure the build system actually detects libarchive. If using a package manager, update or reinstall from its trusted repository, then repeat the protocol and minimal archive tests.

3.4 Validate path syntax and permissions

A missing file, denied directory, or malformed URL can resemble unsupported archive access. Confirm all of the following:

• The outer archive exists and is readable by the user running mpv.
• The internal member name exactly matches the archive listing.
• The complete archive URL is enclosed in quotes.
• Special characters are not being consumed by the shell.
• The archive is not encrypted or password protected.
• A sandboxed package has permission to access the directory.
• A network-mounted archive is available before mpv starts.

Copying a small test archive to a simple local directory can distinguish access and quoting failures from build support. If the local copy works, stop changing mpv packages and correct the original path, mount, permission, or sandbox rule.

3.5 Confirm the archive is readable

Test the archive with the operating system's built-in extraction tool or a reputable archiver. If it cannot list or extract the contents, mpv is not the right place to solve the corruption or unsupported format. Multipart, encrypted, damaged, or unusual archives may require extraction even when mpv has libarchive support.

4. Use Terminal Output and Logs to Identify the Exact Stage

Terminal output is more useful than changing options at random. Run mpv from a terminal even if you normally start it through a desktop shortcut.

4.1 Create a detailed temporary log

Use a clean command with verbose messages and a log file:

mpv --no-config --msg-level=all=v --log-file=mpv-archive-test.log "your-archive-url"

Review the first relevant error around protocol recognition, opening the outer archive, locating the internal member, demuxing, or decoding. Common categories include:

• An unknown or unsupported protocol, suggesting missing build support or incorrect syntax.
• A file-not-found message, suggesting a wrong outer path or internal member name.
• Permission denied, suggesting filesystem or sandbox restrictions.
• An archive read or format error, suggesting damage, encryption, or unsupported archive characteristics.
• A later demuxer or decoder error, meaning archive access probably succeeded.

Do not post logs publicly without checking them for usernames, local paths, URLs, tokens, cookies, or network addresses.

4.2 Use track and playback diagnostics only after opening succeeds

The stats overlay and track list are useful after mpv has opened the internal media. Press the key bound to the stats script in your setup, commonly i in standard configurations, or inspect terminal track output. If audio, video, or subtitles appear in the track list, libarchive has already done its essential job.

At that point, investigate track selection or playback. For example, an external subtitle inside an archive may not be discovered automatically even when an archived video can be opened. Explicitly extract or load the subtitle rather than treating that behavior as proof of missing libarchive.

5. Run a Clean Temporary Test Before Making Permanent Changes

Use a controlled comparison to avoid changing many variables at once.

1. Choose a small, valid, nonencrypted ZIP or other archive format supported by your tools.
2. Place one known playable file inside it with a short, simple filename.
3. Store the archive in a local directory with a simple path.
4. Confirm the archive can be listed and extracted outside mpv.
5. Check mpv --list-protocols for archive support.
6. Launch the internal file with --no-config and quote the full archive URL.
7. If it fails, capture a verbose log.
8. If it succeeds, retest without --no-config.

This sequence identifies whether the difference is the build, archive, path, configuration, or script. Change only the component implicated by the comparison. Once the minimal test and your real file both work, stop adjusting settings. Additional changes can create a new mpv player issue unrelated to the original symptom.

5.1 Use extraction as the safe workaround

If your trusted mpv package lacks libarchive and replacing or rebuilding it is inconvenient, extract the files to a normal directory. Then open the media or playlist directly:

mpv "/path/to/extracted/media.mkv"

For subtitles, keep the subtitle beside the video with a matching base filename, or load it explicitly with --sub-file. For a playlist, verify that its entries still point to valid extracted paths.

Extraction is also the preferred workaround for encrypted, multipart, damaged, or unusually structured archives. It is safer and easier to diagnose than installing an untrusted binary or codec bundle.

6. Quick Fix Checklist

• Run mpv --version and confirm which executable is active.
• Use --list-protocols and search for archive support.
• Test a small valid archive with --no-config.
• Quote the entire archive:// argument to protect shell separators.
• Confirm the outer path and exact internal member name.
• Capture a verbose log with --msg-level=all=v and --log-file.
• Do not change hwdec, HDR, audio, video, or screenshot options unless logs implicate them.
• Compare trusted packages because optional build features differ by operating system and distributor.
• Rebuild mpv after dependency detection if using a self-compiled installation.
• Extract the content as a safe fallback when archive support is unavailable.

7. Frequently Asked Questions

7.1 Does every mpv build include libarchive?

No. libarchive is an optional build dependency, and package maintainers can produce mpv builds with different features. Never infer support from the mpv version number alone. Test the actual executable with the protocol list and a verbose archive-opening command.

7.2 Can an mpv.conf option enable missing libarchive support?

No. A configuration option cannot add a library that was absent when mpv was built. If archive support is genuinely missing, use another trusted package, rebuild mpv with the dependency detected, or extract the files.

7.3 Why does the archive command fail only in PowerShell or a shell?

The shell may interpret characters in the archive URL, particularly a pipe separator. Quote the entire URL and avoid manually escaping only part of it. Also verify that spaces, brackets, ampersands, and backslashes survive exactly as intended.

7.4 Why does an archive work with --no-config but fail normally?

Your build supports the archive, but a configuration entry, profile, script, or input binding is changing the request. Inspect settings related to paths, playlists, subtitle loading, and scripted loadfile commands. Reintroduce customizations gradually rather than deleting the whole configuration folder.

7.5 Will changing hardware decoding or installing codecs fix the error?

Not when the failure occurs while opening the archive. Hardware decoding and codecs become relevant after mpv obtains the media stream. An unknown archive protocol or missing libarchive feature must be fixed at the build, package, path, or extraction level.

7.6 What is the clearest sign that the fix worked?

The archive protocol is recognized, mpv opens the named internal member, and the terminal proceeds to demuxing or displays available tracks. Playback may still expose a separate media, output, or decoder problem, but you should stop changing libarchive-related settings once archive access succeeds.