Skip to content

Building on Linux

Jump to bottom
Martin Vallevand edited this page May 8, 2026 · 10 revisions

Building libmpv

Custom libmpv SDK builds for yauiclient with teletext support (libzvbi) and hardware decoding.

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+.

On Ubuntu 24.04 or newer, prefer the Debian 12 X11+Wayland build below. It uses FFmpeg 8.x, supports Wayland, and is the active Phase 8 target. This legacy section remains for users on older distros (Ubuntu 22.04 and earlier).

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 (Linux)

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 Linux SDK

# Download SDK and runtime for your chosen mpv version
curl -L -o /tmp/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-linux-x86_64.tar.gz
curl -L -o /tmp/libmpv-runtime-v0.41.0-linux-x86_64.tar.gz \
  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 /tmp/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 /tmp/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-dev

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.

Linux x86_64 (Debian 12 build, X11+Wayland)

Forward-looking build for modern desktop Linux. Built on Debian 12 (glibc 2.36) with FFmpeg 8.x and explicit X11 + Wayland support so the same SDK serves both display servers.

Works on Debian 12+, Ubuntu 24.04+, Ubuntu 26.04+, Fedora 38+, openSUSE Leap 15.5+, and any other distribution with glibc ≥ 2.36.

Use this build on Ubuntu 24.04 or newer. For Ubuntu 22.04 or older — or any distro still on glibc 2.31 — use the legacy x86_64 build above.

Feature Profile

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

The runtime tarball bundles libplacebo, libdisplay-info, libjpeg.so.62, libluajit-5.1.so.2 and libbluray.so.2 alongside the FFmpeg .so files, so the same SDK runs on Debian 12, Ubuntu 24.04, Ubuntu 26.04, Debian 13 and any other glibc-2.36+ distro without per-distro dependency tweaks.

MPV Versions

mpv tag FFmpeg libplacebo wayland-protocols libdisplay-info
v0.41.0 8.1 source-built (no Vulkan) 1.47 (source-built) 0.2.0 (source-built)

Prebuilt Downloads (Linux Debian 12, X11+Wayland)

Built on Debian 12 — runs on Debian 12+, Ubuntu 24.04+, and any glibc-2.36+ distro.

v0.41.0

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

Using the Prebuilt SDK (Debian 12, X11+Wayland)

The yauiclient build system expects the libmpv SDK and runtime to be extracted into sdk/ inside the yauiclient repo root. The CMake build then consumes the SDK from there directly, and tools/build-linux.sh propagates the runtime .so files into bin/$BUILD_TYPE/ alongside the binary.

# From inside the yauiclient repo root
cd /path/to/yauiclient

# Download SDK and runtime tarballs
curl -L -o /tmp/libmpv-sdk-v0.41.0-linux-x86_64-debian12.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-linux-x86_64-debian12.tar.gz
curl -L -o /tmp/libmpv-runtime-v0.41.0-linux-x86_64-debian12.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-runtime-v0.41.0-linux-x86_64-debian12.tar.gz

# Extract SDK (provides include/ and lib/libmpv.so + pkgconfig)
mkdir -p sdk
tar xzf /tmp/libmpv-sdk-v0.41.0-linux-x86_64-debian12.tar.gz -C sdk/

# Extract runtime INTO sdk/lib (alongside libmpv.so so the linker resolves
# transitive deps like libplacebo, libdisplay-info, libdav1d, libluajit, etc.)
tar xzf /tmp/libmpv-runtime-v0.41.0-linux-x86_64-debian12.tar.gz -C sdk/lib/

# Sanity check - sdk/lib should now contain libmpv.so plus all bundled deps
ls sdk/lib/

You should see libmpv.so, libmpv.so.2, libmpv.so.2.5.0, libavcodec.so.62, libavformat.so.62, libavutil.so.60, libavfilter.so.11, libswresample.so.6, libswscale.so.9, libplacebo.so.360, libdisplay-info.so.2, libjpeg.so.62, libluajit-5.1.so.2, libdav1d.so.6, and a pkgconfig/ directory.

Install yauiclient build dependencies on Ubuntu 24.04+ / Debian 12+:

# Base packages (X11 build)
sudo apt install -y \
  build-essential cmake ninja-build pkg-config git \
  libglfw3-dev libfmt-dev \
  nlohmann-json3-dev zlib1g-dev \
  libcurl4-openssl-dev libluajit-5.1-dev libass-dev \
  libxss-dev libxpresent-dev

# Add for Wayland builds
sudo apt install -y libwayland-dev wayland-protocols

Then build yauiclient:

# X11 build (default)
./tools/build-linux.sh Release

# Or Wayland build
./tools/build-linux.sh Release --wayland

The build script picks up the SDK from sdk/ automatically (no LIBMPV_SDK_DIR env var needed), and copies libmpv.so plus the runtime .so files from sdk/lib/ into bin/Release/. The output binary at bin/Release/yauiclient carries RUNPATH=$ORIGIN, so it finds its bundled libraries without any LD_LIBRARY_PATH:

cd bin/Release
./yauiclient

The whole bin/Release/ directory is relocatable — copy it anywhere, the binary runs.

Building the Debian 12 SDK from Source

Install Prerequisites

sudo apt-get install -y \
  build-essential nasm yasm pkg-config \
  meson ninja-build cmake git \
  autoconf automake libtool gettext autopoint \
  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 \
  libgl1-mesa-dev libegl1-mesa-dev libgbm-dev libdrm-dev \
  libwayland-dev wayland-protocols libxkbcommon-dev \
  libx11-dev libxext-dev libxrandr-dev libxpresent-dev libxss-dev \
  libpipewire-0.3-dev libpulse-dev libasound2-dev \
  hwdata

Remove dev packages that confuse the build:

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

Build

chmod +x build-libmpv-linux-next.sh
./build-libmpv-linux-next.sh             # default: v0.41.0 with FFmpeg 8.1
./build-libmpv-linux-next.sh v0.41.0     # explicit tag

Output tarballs land in out/ with the -debian12 suffix:

  • libmpv-sdk-v0.41.0-linux-x86_64-debian12.tar.gz
  • libmpv-runtime-v0.41.0-linux-x86_64-debian12.tar.gz

What the runtime tarball contains

The runtime is self-sufficient — it bundles every dynamic dependency that has an unstable SONAME between Debian 12 (build base) and modern targets, and every .so file carries RUNPATH=$ORIGIN so it finds its siblings without needing LD_LIBRARY_PATH or ldconfig:

File Source Reason
libmpv.so.2* source-built the main library
libavcodec.so.62, libavformat.so.62, libavutil.so.60, libavfilter.so.11, libswresample.so.6, libswscale.so.9 source-built FFmpeg 8.1
libplacebo.so.360* source-built newer than older distro versions, no Vulkan
libdisplay-info.so.2* source-built not in Debian 12 main archive
libjpeg.so.62* bundled from build container Ubuntu 26.04 has only libjpeg.so.8
libluajit-5.1.so.2* bundled from build container not installed by default on Ubuntu 26.04
libdav1d.so.6* bundled from build container Ubuntu 26.04 has libdav1d.so.7 (SONAME bumped)

Blu-ray support is not included — Debian 12 ships libbluray.so.2 while Ubuntu 26.04 ships libbluray.so.3, and the Debian 12 build also has a libxml2 ABI dependency (LIBXML2_2.4.30 symbol versioning) that Ubuntu 26.04 has dropped. Bundling either across distros isn't practical. The build script disables libbluray support via -Dlibbluray=disabled in the meson invocation. Developers needing Blu-ray support locally can change that flag and ensure libbluray-dev is installed at build time — they'll get a libmpv that links against their local SONAME, and they'll need to make sure the build environment matches the deployment environment.

Everything else (libwayland-, libEGL, libva-, libdrm, libgbm, libasound, libpulse, libpipewire, libX11 + extensions) resolves to the system Ubuntu/Debian packages — those have stable SONAMEs across recent releases.

Build Script Environment Overrides

Variable Default Purpose
FFMPEG8_VERSION 8.1 FFmpeg 8.x version (used by all mpv tags)
FFMPEG7_VERSION 7.1.1 FFmpeg 7.x — legacy fallback
FFMPEG6_VERSION 6.1.1 FFmpeg 6.x — legacy fallback
LIBPLACEBO_VERSION 7.360.1 libplacebo (source-built, no Vulkan)
LIBDISPLAY_INFO_VERSION 0.2.0 libdisplay-info (source-built)
WAYLAND_PROTOCOLS_VERSION 1.47 wayland-protocols (source-built — adds color-management-v1 needed by mpv 0.41)
ZVBI_VERSION 0.2.44 libzvbi (source-built, static into avcodec)
TARBALL_SUFFIX -debian12 suffix appended to output tarball names
WORK_DIR $PWD/work scratch space
OUT_DIR $PWD/out output tarballs
INSTALL_PREFIX $HOME/.local optional install prefix
JOBS nproc parallel build jobs

macOS x86_64

Built on macOS 13.0+ (Ventura) with deployment target 13.0 for broad compatibility. Works on macOS 13 (Ventura), 14 (Sonoma), and 15 (Sequoia) on Intel x86_64.

Apple Silicon (arm64) — the build script supports arm64 but prebuilt tarballs are not yet available. Build from source on Apple Silicon using the same script.

Feature Profile

  • OpenGL render API (mpv_render_context / MPV_RENDER_API_TYPE_OPENGL)
  • VideoToolbox hardware decoding (H.264, HEVC, AV1)
  • AudioToolbox audio output
  • AVFoundation / CoreMedia integration
  • LuaJIT scripting
  • Blu-ray playback (libbluray)
  • Teletext subtitles (libzvbi — statically linked into avcodec)
  • No Vulkan, no encoders, no capture devices

MPV Versions

mpv tag FFmpeg libplacebo
v0.41.0 7.1.1 source-built (no Vulkan)

Prebuilt Downloads (macOS)

Built on macOS 15.2 (Sequoia) with deployment target 13.0 — compatible with macOS 13+.

v0.41.0

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

Using the Prebuilt macOS SDK

# Download SDK and runtime
curl -L -o /tmp/libmpv-sdk-v0.41.0-macos-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-sdk-v0.41.0-macos-x86_64.tar.gz
curl -L -o /tmp/libmpv-runtime-v0.41.0-macos-x86_64.tar.gz \
  https://raw.githubusercontent.com/wiki/emveepee/libmpv-mingw64-builder/libmpv-runtime-v0.41.0-macos-x86_64.tar.gz

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

# Extract runtime alongside yauiclient binary
mkdir -p ~/yauiclient/build/macos-Release
tar xzf libmpv-runtime-v0.41.0-macos-x86_64.tar.gz -C ~/yauiclient/build/macos-Release

Build yauiclient against the SDK:

export PKG_CONFIG_PATH="$HOME/.local/lib/pkgconfig:$PKG_CONFIG_PATH"
cmake -B build/macos-Release -S . -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLIBMPV_SDK_DIR=$HOME/.local
cmake --build build/macos-Release --parallel $(sysctl -n hw.logicalcpu)

Run (runtime dylibs are found automatically via @executable_path rpath):

./build/macos-Release/yauiclient

Building from Source on macOS

Install Prerequisites

brew install cmake meson ninja pkg-config nasm autoconf automake \
  libtool gettext luajit libbluray lcms2 libass freetype harfbuzz \
  fribidi fontconfig jpeg-turbo zlib libpng uchardet

Build

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

Output tarballs will be in out/:

  • libmpv-sdk-v0.41.0-macos-x86_64.tar.gz
  • libmpv-runtime-v0.41.0-macos-x86_64.tar.gz

Notes

  • The script is fully resumable — stamp files prevent redundant rebuilds of FFmpeg, libplacebo and libzvbi
  • libplacebo is built from source with Vulkan disabled
  • libzvbi is built from source and statically linked into avcodec
  • MACOSX_DEPLOYMENT_TARGET defaults to 13.0 — override to target older macOS versions
  • On Apple Silicon the script auto-detects arm64 and produces macos-arm64 tarballs

Build Script Environment Overrides

Linux (build-libmpv-linux.sh)

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

macOS (build-libmpv-macos.sh)

Variable Default Purpose
FFMPEG7_VERSION 7.1.1 FFmpeg version
LIBPLACEBO_VERSION 7.351.0 libplacebo version (source-built, no Vulkan)
ZVBI_VERSION 0.2.44 libzvbi version (source-built, static)
MACOSX_DEPLOYMENT_TARGET 13.0 Minimum macOS version
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 sysctl -n hw.logicalcpu Parallel build jobs

SDK and Runtime Layout

Linux

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

macOS

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

Runtime (alongside binary or in app bundle Frameworks/):
libmpv.2.dylib  libplacebo.351.dylib
libavcodec.NN.dylib  libavfilter.NN.dylib  libavformat.NN.dylib
libavutil.NN.dylib  libswresample.N.dylib  libswscale.N.dylib
libass.9.dylib  liblcms2.2.dylib  libbluray.3.dylib
libluajit-5.1.2.dylib  libuchardet.0.dylib  libjpeg.8.dylib

The source-built libplacebo coexists safely with any system libplacebo since the sonames differ.

On Linux run sudo ldconfig after installing to /usr/local/lib. On macOS dylibs are found via @rpath — no ldconfig needed.

Clone this wiki locally