Skip to content

Building on Linux

Jump to bottom
Martin Vallevand edited this page Mar 23, 2026 · 10 revisions

Building on Linux

libmpv SDK for Linux x86_64, built on Debian 11 (glibc 2.31) for broad compatibility. Works on Ubuntu 20.04+, Debian 11+, Linux Mint 20+, and any Debian-based distro with glibc 2.31+.

Raspberry Pi / ARM builds are in development. aarch64 support is planned for a future release.

Feature Profile

  • OpenGL render API (mpv_render_context / MPV_RENDER_API_TYPE_OPENGL)
  • VAAPI hardware decoding (Intel/AMD)
  • VDPAU hardware decoding (NVIDIA)
  • ALSA, PulseAudio and PipeWire audio output
  • LuaJIT scripting
  • Blu-ray playback (libbluray)
  • Teletext subtitles (libzvbi — statically linked into avcodec)
  • Wayland + X11 display output
  • Generic x86-64 CPU baseline (SSE2 minimum)
  • No Vulkan, no encoders, no capture devices

MPV Versions

mpv tag FFmpeg libplacebo
v0.41.0 7.1.1 source-built (no Vulkan)
v0.40.0 7.1.1 source-built
v0.39.0 6.1.1 source-built
v0.38.0 6.1.1 source-built
v0.37.0 6.1.1 source-built

Prebuilt Downloads

Built on Debian 11 — compatible with Ubuntu 20.04+, Debian 11+, Mint 20+.

v0.41.0

File Link
SDK libmpv-sdk-v0.41.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.41.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.41.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.41.0-linux-x86_64.sha256

v0.40.0

File Link
SDK libmpv-sdk-v0.40.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.40.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.40.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.40.0-linux-x86_64.sha256

v0.39.0

File Link
SDK libmpv-sdk-v0.39.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.39.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.39.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.39.0-linux-x86_64.sha256

v0.38.0

File Link
SDK libmpv-sdk-v0.38.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.38.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.38.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.38.0-linux-x86_64.sha256

v0.37.0

File Link
SDK libmpv-sdk-v0.37.0-linux-x86_64.tar.gz
SDK SHA256 libmpv-sdk-v0.37.0-linux-x86_64.sha256
Runtime libmpv-runtime-v0.37.0-linux-x86_64.tar.gz
Runtime SHA256 libmpv-runtime-v0.37.0-linux-x86_64.sha256

Using the Prebuilt SDK

# Download SDK and runtime for your chosen mpv version
wget https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz
wget https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-runtime-v0.41.0-linux-x86_64.tar.gz

# Extract SDK to ~/.local
mkdir -p ~/.local
tar xzf libmpv-sdk-v0.41.0-linux-x86_64.tar.gz -C ~/.local

# Install runtime to /usr/local/lib
sudo mkdir -p /usr/local/lib
sudo tar xzf libmpv-runtime-v0.41.0-linux-x86_64.tar.gz -C /usr/local/lib
sudo ldconfig

Install yauiclient build dependencies (x64):

sudo apt install -y \
  build-essential cmake ninja-build pkg-config git \
  libglfw3-dev libfmt-dev \
  nlohmann-json3-dev zlib1g-dev \
  libcurl4-openssl-dev    # or libcurl4-gnutls-dev if already installed

Note: cpr (C++ HTTP library) is not packaged on most distros and will be fetched automatically via CMake FetchContent during the build.

Then build yauiclient (x64) using build-linux.sh from the yauiclient repo:

LIBMPV_SDK_DIR=$HOME/.local ./build-linux.sh Release

Or manually with cmake:

cmake -B build -S /path/to/yauiclient \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLIBMPV_SDK_DIR=$HOME/.local
cmake --build build --parallel

Building on Debian-based Systems

For Ubuntu 20.04+, Debian 11+, Linux Mint 20+ and derivatives.

Install Prerequisites

sudo apt-get install -y \
  build-essential nasm yasm pkg-config \
  meson ninja-build cmake git \
  autoconf automake libtool gettext \
  libass-dev libfreetype6-dev libfribidi-dev libharfbuzz-dev \
  libbluray-dev liblcms2-dev libluajit-5.1-dev \
  libfontconfig-dev libjpeg-dev zlib1g-dev libpng-dev \
  libva-dev libvdpau-dev

Remove these dev packages to prevent mpv picking them up:

sudo apt-get remove -y libavdevice-dev libcdio-dev libcdio-paranoia-dev

Note on libcurl: Only one curl SSL backend dev package can be installed at a time. Keep whichever is already present:

sudo apt-mark hold libcurl4-gnutls-dev   # or libcurl4-openssl-dev

Runtime Dependencies

These need to be present on any machine running yauiclient:

sudo apt install -y \
  libluajit-5.1-2 \
  libjpeg62-turbo \
  libass9 \
  libbluray2 \
  libfontconfig1 \
  libfreetype6 \
  libharfbuzz0b \
  liblcms2-2

Build

chmod +x build-libmpv-linux.sh
./build-libmpv-linux.sh v0.41.0 v0.40.0 v0.39.0 v0.38.0 v0.37.0

If you only need a specific mpv version and want to save time, the FFmpeg build is stamped and reused — building a single tag after the first full run is much faster.

Proxmox VM Settings

A minimal VM is sufficient — the prebuilt FFmpeg stamps mean subsequent builds only rebuild mpv itself:

Setting Value
CPU 4 cores, type: host
RAM 4 GB (3 GB is workable), balloon: disabled
Disk 20 GB SSD
Guest OS Debian 11 for maximum compatibility

balloon: 0 prevents memory reclaim during linking which can cause OOM kills.

Building on Arch Linux

Install Prerequisites

sudo pacman -S --needed \
  base-devel nasm yasm pkgconf meson ninja cmake git \
  autoconf automake libtool gettext \
  libass freetype2 fribidi harfbuzz \
  libbluray lcms2 luajit \
  fontconfig libjpeg-turbo zlib libpng \
  libva libvdpau

Remove conflicting packages:

sudo pacman -R libavdevice 2>/dev/null || true

Build

chmod +x build-libmpv-linux.sh
./build-libmpv-linux.sh v0.41.0

Building on Other Distributions

TBA — guides for Fedora/RHEL, openSUSE and other RPM-based distros are planned. The build-libmpv-linux.sh script should work on most distributions with equivalent packages installed. The main requirements are meson 0.60+, ninja, nasm, and the development headers listed above.

Build Script Environment Overrides

Variable Default Purpose
FFMPEG6_VERSION 6.1.1 FFmpeg version for mpv < v0.40.0
FFMPEG7_VERSION 7.1.1 FFmpeg version for mpv >= v0.40.0
LIBPLACEBO_VERSION 7.351.0 libplacebo version (source-built, no Vulkan)
ZVBI_VERSION 0.2.44 libzvbi version (source-built, static)
WORK_DIR $PWD/work Scratch space for sources and builds
OUT_DIR $PWD/out Output directory for tarballs
INSTALL_PREFIX $HOME/.local Optional install prefix
JOBS nproc Parallel build jobs

Build Script Notes

  • libplacebo is built from source with Vulkan disabled — avoids pulling in libavdevice, libcaca, libSDL2 and FireWire libraries
  • libzvbi is built from source and statically linked into avcodec-NN.so — no extra .so to ship
  • The script auto-upgrades autoconf if the system version is too old for zvbi (Debian 11 ships 2.69, zvbi needs 2.71+)
  • The script is fully resumable — stamp files prevent redundant rebuilds. Delete a stamp to force a rebuild of that component
  • Remove libavdevice-dev and libcdio-dev before building — mpv's meson finds them by scanning /usr/lib directly

SDK and Runtime Layout

SDK:
include/mpv/client.h  render.h  render_gl.h  stream_cb.h
lib/libmpv.so.2  libmpv.so  pkgconfig/libmpv.pc

Runtime (/usr/local/lib/):
libmpv.so.2  libplacebo.so.351
libavcodec.so.NN  libavfilter.so.NN  libavformat.so.NN
libavutil.so.NN  libswresample.so.N  libswscale.so.N

The source-built libplacebo.so.351 coexists safely with any system libplacebo since the sonames differ. Run sudo ldconfig after installing to /usr/local/lib.

Clone this wiki locally