Compiling mpv on Mac OS X

Note: This guide is outdated and won’t be updated anymore.

Hint: You can get ready to use builds here.



This is a guide to compiling mpv, a fork of the MPlayer family and the current recommended media player on *nix. It has more active development and some features like nicer CLI output, an On Screen GUI and high quality OpenGL video output.
This will ensure you are using the latest, most up-to-date high quality playback that you can get for OS X.
This guide is targeted at advanced users and assumes basic commandline-knowledge. This guide may not always be up to date, so you may have to do your own research. mpv on OS X requires at least 10.7.


  1. Only for <10.9:
  2. Install Homebrew by running the command
    ruby -e "$(curl -fsSL"
    in a Terminal, install the Command Line Tools when asked.
  3. Install some other needed stuff: sudo easy_install docutils
  4. Build mpv and the needed dependencies using homebrew:
    The command lines you'll need are:

    • export LC_ALL=en_US.UTF-8 ; export LANG=en_US.UTF-8
    • brew install --HEAD --with-bundle --with-bluray-support --with-libdvdread --with-little-cms2 --with-lua --with-bundle mpv
  5. If you want to have an .app-bundle in ~/Applications: brew linkapps mpv
  6. Done!


To set mpv as the default program to open .filetypes, get Finder-info on the filetype you want to associate, select under Open with: and click the “Change All…” button. You can view options and keybinds here or by typing man mpv into Terminal. You can quit this dialogue any time by pressing q. mpv can also be launched by typing mpv into Terminal, dragging the file into the terminal window and hitting enter.

To make your own configuration, create the folders ~/.config/mpv and create the file mpv.conf in there. Paste the the options you want to change in that file (see mpv’s documentation for all possible options).

If you have sufficient GPU power, it is recommended to use the opengl-hq video-output (requires Intel HD4000 or better). To use this add this line to your config:


  • Remember to keep everything up-to-date using brew update. Since mpv is on –HEAD, brew update won’t work for it. You need to uninstall and reinstall (brew rm mpv && brew install --HEAD --with-bundle --with-bluray-support --with-libdvdread --with-little-cms2 --with-lua --with-bundle mpv), as it’s a HEAD only formula homebrew is not smart enough to figure out the version it built.
  • Having MacPorts or Fink installed may break brew. See brew doctor if you run into problems.
  • If you have problems, join the #mpv channel on freenode or open an issue on the Github page. Please use the comments here only for problems related to CGi releases.

Original guide written by valtism. Modified.

155 Responses to Compiling mpv on Mac OS X

  1. Paul writes:

    As instructed I started with removing pbo, nothing changed.

    I tried removing deband next and it worked, mpv has smooth playback again with opengl-hq on 9400m. Thanks.

    I used this as a reference –

    vo_opengl: implement debanding (and remove source-shader)

  2. ktgw writes:

    Never had any problems with compiling mpv until now, with El Capitan:

  3. ImportError writes:

    @ktgw Did you read the error message? It says in plain english what is wrong.

    ImportError: No module named ‘setuptools’

  4. ktgw writes:

    Hi, @ImportError. Unfortunately it wasn’t it. It seems the post-install of python3 didn’t complete successfully. So I needed to use: ‘brew post install python3’ and then: ‘pip3 install –upgrade pip setuptools’.
    Well, hope it helps whoever get this error on El Capitan.

  5. rich writes:

    nowadys MPV requires Mountain Lion .

    when trying to install MPV via Homebrew on MacOs X 10.7.5 i get the following

    Warning: You are using OS X 10.7.
    We (and Apple) do not provide support for this old version.
    You may encounter build failures or other breakages.
    mpv: OS X Mountain Lion or newer is required.

    any way to overcome this`?

  6. zhangshangjin writes:

    If the installation fails,
    brew reinstall python3,
    brew uninstall python3

  7. mild09 writes:

    Any updates to the builds?

  8. Gnut writes: plz update last ver 0.17.0

  9. Begood writes:

    Hi, love your work !
    Please keep going to update mpv for mac 🙂

  10. plasmacutter writes:

    Build fails first try with those instructions, but re-trying after “brew reinstall python3” works.
    app bundle produced (build git-aaafbfc) works

    Until such time as chris is able to upload the build here’s the app I built : [removed]

    App is configured for insane video quality. If this is slow for you, simply control(or right) click on app, show package contents, go to resources, open mpv.conf, uncomment first line and delete all lines below it.

  11. x-skyber writes:

    Playing 5.1 surround sound audio mkv file giving me low voice in my stereo speakers. Anyone knows what configuration I need to downmix 5.1 to stereo? The audio-channels=2 not making any difference…

  12. Anthony writes:

    If you have compilation issues, there may be residual libraries in /usr/local/lib which are conflicting with mpv. In order to solve this, run “brew doctor” and copy all the unexpected libraries it lists into a text file called “unexpected.txt”. The whitespace in the file doesn’t matter, just copy it and leave as is, there’s no reason to be a perfectionist about this. Now, make the directory /usr/local/unexpected by running the command “sudo mkdir /usr/local/unexpected”.

    Once you’ve got that set up, assuming you have your text file saved to the desktop, run this command:

    for file in $(cat ~/Desktop/unexpected.txt); do sudo mv “$file” /usr/local/unexpected/; done

    What this will do is move all the libraries listed in the text file into /usr/local/unexpected. Most people suggest you simply remove these troublesome libraries because they’re likely residual from previous installations. However, in the event that this isn’t the case, it’s nice to have a backup. Now, you can move a library back from /usr/local/unexpected to /usr/local/lib if you ever run into problems due to a missing library.

    P.S. You can simplify updating mpv by creating an alias in your .bash_profile file. Open up terminal and enter “nano ~/.bash_profile”. Move the cursor to the bottom of the file and enter the following on a separate new line:

    alias mpvup=’brew rm mpv && brew install –HEAD –with-bundle –with-bluray-support –with-libdvdread –with-little-cms2 –with-lua –with-bundle mpv’

    Additionally, you may mark a comment above it with the ‘#’ symbol. I suggest leaving a comment with a link to this blog post. When you’re done, save the file with Ctrl+X. Finally, run “source ~/.bash_profile” for the change to take effect. Now anytime you run “mpvup”, your mpv application will be removed and recompiled to the latest version.

    P.P.S. This blog mentions using easy_install, but I would recommend using pip instead. Since the newest mpv uses python3, use the pip3 command to correspond to that version. So, to install docutils you would run “pip3 install docutils”. If you haven’t installed python3 already though, you first need to install it with homebrew “brew install python3” and then update pip and setuptools “pip3 install –upgrade pip setuptools”. You can still install things to python 2.7 using the regular pip command.

  13. Begood writes:

    Thanks for the tips, no problem to compile mpv but when I used “pip3 install –upgrade pip setup tools” it respond “You are using pip version 8.0.2, however version 8.1.1 is available.
    You should consider upgrading via the ‘pip install –upgrade pip’ command.”

    It is normal ?

  14. dankzel writes:

    Any change of updating your OSX mpv builds? This “compiling” business is a little above my head…

  15. exprimelimones writes:

    Is it possible to install everything necessary to compile mpv from a no-admin account?

  16. Paco writes:

    Thanks for pointing out this far superior alternative to MplayerX. I found out that the MplayerX installer from the developer had 15/45 malware positives on VirusTotal and the SourceForge build has no malware but it is and always has been a slow-to-open piece of bloatware. It takes a full minute to open the smallest video file on an 8-core Xeon Mac Pro.

    I have had no end of problems trying to install mplayer via brew because it didn’t support OSD. I finally hacked the rb file to get OSD support but I had trouble appifying it. I wanted an app to associate with media files. I spent hours trying to install mpv with brew with error after error, including sha256 errors on downloaded files, so I gave up. I next downloaded the ‘official’ stolendata build but it crashed on opening. I finally downloaded your latest version and am happy to say it works. It is half the size of MplayerX and opens in seconds. Thanks for providing it.

    I am having problems with mounted Blu Ray discs. I tried opening the main BDMV directory and got lots of errors and only images opened, index.bdmv in that directory, even m2ts files, but nothing works. Is the latest build built with Blu Ray support, or is there some other way to open a disc? Any config settings I should be adding?

    Also, the OSD does not stay onscreen. I increased the duration in the config file but it’s not the same as mplayer, which keeps the OSD onscreen until you toggle it off. I could find no configuration parameter that allows this behavior.

  17. Gé van Gasteren writes:

    I’ve downloaded a ready-to-use build and it works nicely on Mac OS X 10.11.
    I also found the info how to control MPV with the keyboard during playing.
    What I can’t find is how to use the command line on Mac OS X.
    I know, this is probably more about the Mac than about MPV, but I’m sure you guys know how to do this.
    I’ve found in the manual that -sub will add a subtitles file, but that can’t be the actual command, can it?
    E.g. I typed this into Terminal:
    -sub “vaya con dios (2002)”
    but it just says “-bash: -sub: command not found”. I guess what’s missing is a reference to MPV?

    Thanks if you can help me with this!

    • ChrisK writes:

      You can just drag subtitles onto the window to add them.

      Look for a general tutorial on how to use a UNIX/POSIX command-line before trying to use a command-line.

  18. 1 news tonight writes:

    1 multichannel audio and a powerful performance
    with maximum speed delivered with the power of 3 grams Intel
    Core Processors. This business of trading is hard enough and now we should make the most of every edge on the market that’s available to us.
    Just finished watching Dabangg, Abhinav Kashyap’s sterling debut performance.

Leave a Reply

Your email address will not be published. Required fields are marked *