CLI tool
mpv-player/mpv avatar
mpv-player/mpv

mpv: A command line media player that puts configuration before convenience

🎥 Command line media player

38,137 stars3,659 forksCNOASSERTION

At a glance

What is it?
mpv is a free command line media player built around FFmpeg and libplacebo, with a shader-based video pipeline and a scriptable control interface. It suits users who want precise control, but it demands modern hardware and a tolerance for sparse release support.
Who is it for?
Adopt mpv if you are a Linux, Windows, or macOS user who wants a scriptable, config-driven media player and can meet its hardware requirements: a somewhat capable CPU, a decent GPU, and a modern OS. Do not adopt it if you need power-efficient playback on embedded or integrated GPUs, or if you rely on long-term support for a specific release, since only the latest release is maintained and releases are cut only once or twice a year.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • mpv-player/mpv38,137 ★ · +1,558
Star history
Repository2026-08-182026-11-15
mpv-player/mpv36.6k38.1k

1,558 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What mpv actually is and who it serves

mpv is a free media player that runs from the command line. It is not a graphical application in the usual sense, though it includes an on-screen controller written in Lua. The README positions it as a player for a wide variety of media formats, codecs, and subtitle types, but the emphasis is on flexibility rather than ease. The intended user is someone who is comfortable editing configuration files, passing command line options, and possibly writing scripts. The project's own language is telling: it lists system requirements in terms of CPU and GPU capability, not in terms of clickable menus. If you want a double-click player, this is not it. If you want a player you can drive from a terminal, a script, or a custom keybinding, mpv is built for that workflow.

The shader-based rendering pipeline and its hardware cost

The most distinctive architectural choice in mpv is that its main video output uses shaders for rendering and scaling, rather than the GPU's fixed function hardware. That means the GPU is doing general-purpose compute work for every frame, which gives the renderer more control over scaling quality and color handling. The trade-off is direct: the README warns that low-power GPUs may cause tearing, stutter, and other issues, and that hardware decoding is not enabled by default. Hardware decoding can be turned on with the --hwdec option, but the default is software decoding. This is a deliberate design decision, not an oversight. The project states that its focus is not on power-efficient playback on embedded or integrated GPUs. If you are on a laptop with an integrated GPU and expect smooth 4K playback out of the box, you will likely be disappointed. The README suggests --profile=fast as a workaround for weak GPUs, but it frames that as a recommendation, not a guarantee.

Build process: meson, dependencies, and the libplacebo subproject

Compiling mpv from source requires meson, and the README gives a three-command sequence: meson setup build, meson compile -C build, and meson install -C build. That is the happy path. The real work is in the dependencies. The README lists essential libraries: FFmpeg libraries (libavutil, libavcodec, libavformat, libswscale, libavfilter, and either libswresample or libavresample), libplacebo, zlib, iconv, libass, and X development headers on Linux. Optional but common additions include Lua for the OSC and youtube-dl integration, libjpeg for screenshots, and uchardet for subtitle charset detection. A notable convenience is that meson can pull libplacebo as a subproject from a git checkout, which avoids the problem of a distribution shipping an older libplacebo. The README shows the exact commands: mkdir -p subprojects, then git clone from code.videolan.org. This is a practical escape hatch for users who want the latest mpv but cannot get a recent libplacebo from their package manager.

Hardware decoding and the --hwdec option

The README is explicit that hardware decoding must be manually enabled with --hwdec. This is a deliberate default, and it has consequences. On a machine with a weak CPU, software decoding may not keep up with realtime playback, and the user has to know about the option and set it. On Linux, the README mentions nvdec and vaapi libraries as optional dependencies for hardware decoding, and it notes that for good nvidia support, nv-codec-headers must be installed and found by configure. This is not a zero-configuration feature. The project's stance is that hardware decoding is a fallback for slow CPUs, not a primary path. The practical implication is that a first-time user who plays a high-resolution video on a modest laptop may see stutter and assume the player is broken, when in fact they need to pass --hwdec or use --profile=fast. The documentation does not hide this, but it is buried in the system requirements section, not in a quick start guide.

Release cycle: sparse releases and no long-term support

mpv's release policy is unusual for a widely used tool. A release is cut once or twice a year and assigned a 0.X.0 version number. The README states that no further maintenance is done on a release except in the event of security issues. Releases other than the latest are unsupported and unmaintained. The stated goal is to make Linux distributions happy, and the expectation is that distributions will apply their own patches. This has real consequences for adopters. If you install mpv from your distribution's package manager, you may be on a release that is already unsupported upstream. The latest tagged release is v0.41.0 (2025-12-21), a git-release development build is dated 2026-06-04, and the last push to the repository was on 2026-11-02, so development continues on master. For a user who wants stability, this is a warning: you are either on the moving master or on a release that will not receive fixes.

Scripting and control interfaces visible in the repository

The README points to a client API changelog and an interface changelog, which indicates that mpv exposes a C API for external control. The README also mentions Lua as an optional dependency, required for the OSC pseudo-GUI and youtube-dl integration. That Lua dependency is a sign of how the project thinks about extensibility: the on-screen controller is not a compiled feature, it is a script. The wiki lists user scripts as a category, which suggests a community ecosystem of Lua scripts that extend the player. The practical takeaway is that mpv is not just a player, it is a platform for building playback workflows. You can write a script to change behavior, or you can embed mpv in another application via its C API. For an engineer evaluating mpv, this is the strongest argument for adoption: the control surface is open and scriptable.

Limitations and failure modes to consider

mpv has several documented failure modes. The first is hardware: the README warns that low-power GPUs may cause tearing and stutter, and that hardware decoding is not enabled by default. The second is OS support: the README says that only recent Linux distributions are actively supported, and that compatibility with older hardware or operating systems is not guaranteed. The third is the release policy: if you depend on a specific release version, you are on your own after the next release comes out. The fourth is the build complexity: the dependency list is long, and the README notes that FFmpeg itself may need to be built with specific flags for features like native DASH playback, which it describes as having security implications and bugs. For a user who just wants to play a video file, these are not trivial barriers. The project's own language is candid: if things work on old hardware, consider it a happy accident. That is a direct statement of the project's priorities, and it should be read as a warning, not a reassurance.

Alternatives and how they differ in approach

The most direct alternative to mpv is VLC, which is also a free media player but takes a fundamentally different approach. VLC ships as a graphical application with a default set of features that work out of the box, including hardware decoding on by default on most platforms. VLC does not require a build process for typical users. If you want a player that just plays files with minimal configuration, VLC is the safer choice. If you want a player where you can control every scaling decision and write Lua scripts to alter behavior, mpv gives you that control at the cost of setup effort and hardware demands. A second alternative is the FFmpeg command line itself, which can decode and play media but is not a player in the interactive sense; mpv builds on FFmpeg libraries and adds the interactive and scripting layer.

Editorial conclusion

Adopt mpv if you are a Linux, Windows, or macOS user who wants a scriptable, config-driven media player and can meet its hardware requirements: a somewhat capable CPU, a decent GPU, and a modern OS. Do not adopt it if you need power-efficient playback on embedded or integrated GPUs, or if you rely on long-term support for a specific release, since only the latest release is maintained and releases are cut only once or twice a year. Before adopting, verify that your GPU drivers are current, especially on Windows, and check whether your distribution's FFmpeg and libplacebo versions satisfy mpv's build requirements, or plan to use the provided libplacebo subproject.

Frequently asked questions

Which player is better, mpv or VLC?

That depends on what you need. The README states that mpv is a free command line media player supporting a wide variety of media file formats, audio and video codecs and subtitle types, that the main video output uses shaders for rendering and scaling rather than GPU fixed function hardware, and that its focus is not power-efficient playback on embedded or integrated GPUs.

How do I use an mpv player?

It is driven from the command line and configured like any other program. The manual is at mpv.io/manual/master, the wiki carries a User Scripts page, and Lua is an optional dependency needed for the OSC pseudo-GUI and youtube-dl integration. To see every build option the project exposes, configure a build directory and run meson configure build.

Is the mpv player free?

The README describes mpv as a free, as in freedom, media player, and the repository carries both LICENSE.GPL and LICENSE.LGPL at the root, so the software is open source under a dual licence.

Can I download an MPV player for Windows 11?

The README points to mpv.io/installation for semi-official builds and third-party packages. The system requirements list Windows 10 1607 or later, which Windows 11 satisfies, and the documentation notes you should make sure your graphics drivers are current on Windows.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/mpv-player-mpv.svg)](https://hysenlabs.com/projects/mpv-player-mpv)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/mpv-player-mpv.svg)](https://hysenlabs.com/projects/mpv-player-mpv)

Was this useful?