Portable FFmpeg Builds for macOS, Windows, and Linux

April 9, 2026

Shipping FFmpeg with a desktop app sounds simple until you need repeatable builds across multiple operating systems, consistent codec support, and artifacts you can actually redistribute.

That is why I published ffmpeg-builder: an open-source build system for producing portable FFmpeg binaries for macOS, Windows, and Linux.

The repository is designed for two use cases:

  • building FFmpeg locally when you need full control over codecs and flags
  • running the same build in CI so releases are reproducible and easy to package

Why this exists

For Video Commander, FFmpeg is a core dependency for conversion, analysis, and delivery workflows. Relying on whatever happens to be installed on a system is fine for development, but it is not enough when you need a known-good binary with predictable features.

The goal with ffmpeg-builder is to make FFmpeg builds boring:

  • one profile defines the FFmpeg version, codec set, licensing mode, and platform defaults
  • the same profile works locally and in GitHub Actions
  • the output is packaged as a portable archive with binaries, manifest metadata, configure flags, and license files

This is especially useful for desktop apps, internal tools, CI pipelines, and test environments where you need the same behavior every time.

What the project builds

ffmpeg-builder produces zipped artifacts per OS and architecture, ready to drop into another project.

Artifacts include:

  • bin/ffmpeg
  • bin/ffprobe
  • optional ffplay
  • build-manifest.json
  • configure-flags.txt
  • bundled LICENSES/ files for included libraries

The current project supports portable builds for:

  • macOS Apple Silicon and Intel
  • Windows x86_64 via MSYS2/MinGW
  • Linux x86_64, with optional aarch64 support in CI

Declarative profiles

The most important part of the repository is the profile system. Instead of hardcoding every codec toggle in shell scripts, builds are described in YAML.

For example, the profile used for Video Commander enables a practical desktop-oriented set of codecs and libraries:

name: video-commander
ffmpeg:
  version: 8.0.1
  enable_ffplay: false
  gpl: true
  nonfree: false
  ld_static: true
codecs:
  x264: true
  x265: true
  aom: true
  svtav1: true
  vpx: true
  opus: true
  ass: true
  vmaf: true

That gives Video Commander a consistent FFmpeg feature set across platforms without maintaining separate hand-tuned scripts for every release.

Included codec libraries

By default, ffmpeg-builder can compile and package commonly needed libraries including:

  • x264
  • x265
  • SVT-AV1
  • AOM-AV1
  • libvpx
  • Opus
  • libass
  • libvmaf

fdk-aac is supported as an opt-in nonfree dependency, but it is disabled by default. That distinction matters. Nonfree FFmpeg builds cannot be redistributed the same way as redistribution-safe builds, so the repository keeps that choice explicit in the profile.

Local build flow

Running it locally is intentionally simple:

git clone https://github.com/video-commander/ffmpeg-builder.git
cd ffmpeg-builder

./scripts/bootstrap-macos.sh
PROFILE=profiles/video-commander.yml ./scripts/build-ffmpeg.sh
./scripts/package.sh

Equivalent bootstrap scripts are included for Linux and Windows.

The result is a packaged artifact in dist/ that can be archived, attached to a release, or consumed by another application.

Good fit for CI

The same repository is designed to run in GitHub Actions, which means build definitions do not drift between a developer machine and release automation.

That matters for FFmpeg more than most dependencies. Codec combinations, system libraries, and licensing choices can quietly change behavior if builds are not pinned and documented. ffmpeg-builder keeps those decisions visible in the repository instead of burying them inside an opaque CI job.

Who this is for

ffmpeg-builder is useful if you need to:

  • ship a desktop app with a known FFmpeg build
  • standardize FFmpeg across a team or CI pipeline
  • enable specific codec libraries without manually reworking every platform script
  • keep licensing choices explicit and reviewable

If that sounds familiar, the repository is available here:

github.com/video-commander/ffmpeg-builder

Closing note

Video Commander still works with system-installed FFmpeg, and that remains the default workflow for end users today. ffmpeg-builder exists for the cases where you need a portable, reproducible, application-specific FFmpeg toolchain rather than whatever happens to be on PATH.