From 80a6a467c341900cbfb5067ab4a1fac5403ad37a Mon Sep 17 00:00:00 2001 From: Bradley Sepos Date: Thu, 20 Aug 2026 08:40:16 -0400 Subject: [PATCH] docs: Update Fedora and Ubuntu, Linux and Windows build guides. --- .../en/latest/developer/build-linux.markdown | 54 ++++-- .../latest/developer/build-windows.markdown | 172 ++++++++++-------- .../install-dependencies-fedora.markdown | 10 +- .../install-dependencies-ubuntu.markdown | 84 ++++++++- 4 files changed, 212 insertions(+), 108 deletions(-) diff --git a/source/docs/en/latest/developer/build-linux.markdown b/source/docs/en/latest/developer/build-linux.markdown index a43a0450..908130da 100644 --- a/source/docs/en/latest/developer/build-linux.markdown +++ b/source/docs/en/latest/developer/build-linux.markdown @@ -35,41 +35,55 @@ Dependency installation instructions are available for the following distributio - [Ubuntu](install-dependencies-ubuntu.markdown) - [Void](install-dependencies-void.markdown) - ## Building HandBrake Clone the HandBrake repository. git clone https://github.com/HandBrake/HandBrake.git && cd HandBrake -Build HandBrake. +You can enable or disable various HandBrake features via additional configure parameters. The following is a short list of common parameters; see `./configure --help` for a complete list. - ./configure --launch-jobs=$(nproc) --launch - -The following optional parameters are commonly used: +| Parameter | Description | +|------------------|--------------------------------------------------------------| +| --enable-fdk-aac | Enable FDK-AAC audio encoder[^fdk-aac-license] | +| --enable-nvenc | Enable Nvidia NVENC video encoder | +| --enable-nvdec | Enable Nvidia NVDEC video decoder | +| --enable-vaapi | Enable VAAPI video encoder/decoder | +| --enable-qsv | Enable Intel Quick Sync Video encoder/decoder | +| --enable-vce | Enable AMD VCN video encoder | +| --enable-amfdec | Enable AMD VCN video decoder | +| --enable-libdovi | Enable libdovi for Dolby Vision HDR support | +| --disable-gtk | Disable the GTK graphical interface; only build HandBrakeCLI | + +Build HandBrake. Append any desired configure parameters to this command. -| Parameter | Description | -|------------------|---------------------| -| --enable-qsv | Enable support for the Intel QuickSync Video Decoder and Encoder | -| --enable-nvdec | Enable support for the Nvidia NVDec Decoder | -| --enable-vce | Enable support for the AMD VCN video encoder | -| --enable-libdovi | Enable support for Dolby Vision | -| --disable-gtk | Build only HandBrakeCLI on Linux | + ./configure --launch-jobs=$(nproc) --launch -For a full listing of options, use the command: +When building completes successfully, these important artifacts are produced: - ./configure --help - -When complete, you will find `HandBrakeCLI` in the `build` directory. If the graphical interface is enabled, you will also find `ghb` in the `build/gtk/src` directory. +- `HandBrakeCLI` in the `build` directory, which is the HandBrake command line interface. +- `ghb` in the `build/gtk/src` directory, which is the HandBrake [GUI](abbr:Graphical User Interface) for Linux. It will not exist if you disabled the graphical interface by configuring with `--disable-gtk`. -Install HandBrake (optional). When installing the graphical interface, icon and desktop files for the Applications menu will be also installed. +Install HandBrake (optional). When installing the graphical interface, icon and desktop files for the Applications menu are also installed. sudo make --directory=build install - -If you wish to then uninstall - + +To uninstall HandBrake, run the following. + sudo make --directory=build uninstall +## Troubleshooting + +If building HandBrake fails, continue building as much as possible, then build serially (only one job at a time) and investigate any errors printed at the end. + + make --directory=build --jobs=$(nproc) --keep-going || make --directory=build --jobs=1 + +Build failures are often due to missing dependencies. Ensure you have followed all of the above instructions for installing dependencies. + To start over, simply remove the `build` directory. rm -rf build + +If you still have issues, someone may be able to help via HandBrake's [Community support](../help/community-support.markdown) channels. + +[^fdk-aac-license]: The FDK AAC encoder is only provided in source code form and is not fully compatible with the GNU General Public License Version 2 used by HandBrake. Builds including FDK AAC must be for personal use only and may not be distributed. Do not share the build product with others. \ No newline at end of file diff --git a/source/docs/en/latest/developer/build-windows.markdown b/source/docs/en/latest/developer/build-windows.markdown index e72dabcf..144ab138 100644 --- a/source/docs/en/latest/developer/build-windows.markdown +++ b/source/docs/en/latest/developer/build-windows.markdown @@ -16,108 +16,130 @@ License_URL: https://handbrake.fr/docs/license.html Building HandBrake for Windows ============================== -## Command line interface and LibHB - -Building the HandBrake [CLI](abbr:Command Line Interface) and LibHB (`hb.dll`) for Windows requires Linux and a recent [MinGW-w64](https://mingw-w64.org/) toolchain. A recent Ubuntu LTS release is recommended; recent releases from other distros may work as well. Virtual machines and [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) are supported. In all cases, we recommend you build the MinGW-w64 toolchain using our instructions and the included script, as some packaged versions have issues that can produce non-functioning builds. - -### Installing dependencies on Ubuntu - -The following instructions are for [Ubuntu](https://www.ubuntu.com) 22.04 (Jammy Jellyfish) - -Basic requirements to run commands: - -- sudo (for normal user accounts) - -Dependencies: - -- autoconf -- automake -- autopoint -- build-essential -- cargo -- cmake -- clang -- curl -- gcc -- git -- libssl-dev -- libtool -- libtool-bin -- m4 -- make -- meson -- nasm -- ninja-build -- patch -- pkg-config -- rustc -- tar -- zlib1g-dev - -Additional MinGW-w64 toolchain dependencies: - -- bison -- bzip2 -- curl -- flex -- g++ -- gzip -- pax - -Install dependencies. - - sudo apt-get update - sudo apt-get install automake autoconf autopoint build-essential cmake gcc git intltool libtool libtool-bin m4 make meson nasm ninja-build patch pkg-config tar zlib1g-dev clang curl libssl-dev - curl https://sh.rustup.rs -sSf | sh - source "$HOME/.cargo/env" - cargo install cargo-c - rustup target add x86_64-pc-windows-gnu +Building HandBrake for Windows requires two steps: + +1. Cross-compiling the LibHB core library (`hb.dll`) and HandBrake [CLI](abbr:Command Line Interface) on Linux using a [MinGW-w64](https://mingw-w64.org/) toolchain +2. Building the HandBrake [GUI](abbr:Graphical User Interface) on Windows using [Microsoft Visual Studio Community](https://visualstudio.microsoft.com/vs/community/) + +LibHB can also be downloaded from [HandBrake development snapshot builds](https://github.com/HandBrake/handbrake-snapshots/) if you only want to build the HandBrake GUI on Windows. If you want to run the latest unreleased HandBrake code without building anything yourself, you can download a development snapshot of HandBrake from there, with everything including the GUI, and skip the rest of this guide. + +## Cross-compiling LibHB and HandBrake CLI on Linux + +These instructions are for recent [Ubuntu Linux](https://ubuntu.com/) [LTS](abbr:Long-Term Support) releases. Recent releases from other Linux distros may work as well, but are not officially supported by the HandBrake project. Physical machines, virtual machines, containerized machines, and [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/) are all valid options for running Ubuntu Linux. + +### Installing dependencies + +Begin by installing all dependencies specified in the guide [Installing dependencies on Ubuntu](install-dependencies-ubuntu.markdown). + +### Cross-compiling for Windows ARM machines + +*This section is for running HandBrake on ARM-based Windows machines only (not x64). You can find the type of machine you have by opening Windows Settings and navigating to System > About.* + +After installing the Ubuntu dependencies, continue as follows. + +To build with Dolby Vision support, install the additional Rust dependencies for Windows ARM. + + rustup target add aarch64-pc-windows-gnullvm + +Download and extract the prebuilt LLVM MinGW-w64 toolchain, available from [HandBrake toolchains releases](https://github.com/HandBrake/HandBrake-toolchains/releases) and [LLVM MinGW project releases](https://github.com/mstorsjo/llvm-mingw/releases). + + PREV_DIR="${PWD}" + mkdir -p "${HOME}/toolchains" + cd "${HOME}/toolchains" + curl -LO "https://github.com/HandBrake/HandBrake-toolchains/releases/download/1.0/llvm-mingw-20260324-ucrt-ubuntu-22.04-$(uname -m).tar.xz" + tar -xf "llvm-mingw-20260324-ucrt-ubuntu-22.04-$(uname -m).tar.xz" + export PATH="${HOME}/toolchains/llvm-mingw-20260324-ucrt-ubuntu-22.04-$(uname -m)/bin:${PATH}" + cd "${PREV_DIR}" + + # command to make persistent across sessions (optional) + # replace "${HOME}/.bashrc" with the path to your shell startup script if different + # echo "export PATH=\"${HOME}/toolchains/llvm-mingw-20260324-ucrt-ubuntu-22.04-$(uname -m)/bin:\${PATH}\"" >> "${HOME}/.bashrc" + +Clone the HandBrake repository. + + git clone https://github.com/HandBrake/HandBrake.git && cd HandBrake + +Build LibHB and the HandBrake CLI using the cross-compilation toolchain. + + ./configure --cross=aarch64-w64-mingw32 --launch-jobs=$(nproc) --launch -Install the additional dependencies required to build the MinGW-w64 toolchain. +### Cross-compiling for Windows x64 machines - sudo apt-get install bison bzip2 flex g++ gzip pax +*This section is for running HandBrake on x64-based Windows machines only (not ARM). You can find the type of machine you have by opening Windows Settings and navigating to System > About.* +After installing the Ubuntu dependencies, continue as follows. -### Building the MinGW-w64 toolchain and HandBrake +To build with Dolby Vision support, install the additional Rust dependencies for Windows x64. + + rustup target add x86_64-pc-windows-gnu Clone the HandBrake repository. git clone https://github.com/HandBrake/HandBrake.git && cd HandBrake -Build the MinGW-w64 toolchain using the included script, where `username` is your user name. Feel free to choose a different output path, if desired. +Install the additional dependencies required to build the GCC MinGW-w64 toolchain. - scripts/mingw-w64-build x86_64 /home/username/toolchains/ + sudo apt-get install bison bzip2 curl flex g++ gcc gzip m4 make pax -This process will take a few minutes, then provide you with instructions for adding the resulting binaries location to your environment's `PATH`. Do this now. +Build the GCC MinGW-w64 toolchain using the `mingw-w64-build` script included with HandBrake and available from [mingw-w64-build](https://github.com/bradleysepos/mingw-w64-build). -Build HandBrake. For higher quality audio, enable the FDK AAC encoder by appending `--enable-fdk-aac`. Builds including FDK AAC must be for personal use only and may not be distributed.[^fdk-aac-license] + scripts/mingw-w64-build x86_64 + +The process will take a few minutes and then provide you with a command to run to update your environment's `PATH` variable. Do this now to ensure that HandBrake's build system can find the toolchain. + +Build LibHB and the HandBrake CLI using the cross-compilation toolchain. ./configure --cross=x86_64-w64-mingw32 --launch-jobs=$(nproc) --launch -When complete, you will find `HandBrakeCLI.exe` in the `build` directory and `hb.dll` in `build/libhb`. +### Locating the build product + +When cross-compiling completes successfully, two important artifacts are produced: + +- `HandBrakeCLI.exe` in the `build` directory, which is the HandBrake command line interface. If you do not intend to build and use the graphical interface, this program is all you need. Copy it to your Windows installation, and run it via the Windows Command Prompt or Windows Powershell in the Windows Terminal app. +- `hb.dll` in the `build/libhb` directory, which is the LibHB core library used by the HandBrake GUI for Windows. You will need to copy this file to the output folder on your Windows machine after you have built the graphical interface in the next section. + +### Troubleshooting + +If building HandBrake fails, continue building as much as possible, then build serially (only one job at a time) and investigate any errors printed at the end. + + make --directory=build --jobs=$(nproc) --keep-going || make --directory=build --jobs=1 + +Build failures are often due to missing dependencies. Ensure you have followed all of the above instructions for installing dependencies. To start over, simply remove the `build` directory. rm -rf build +If you still have issues, someone may be able to help via HandBrake's [Community support](../help/community-support.markdown) channels. -## Graphical interface +## Building the HandBrake GUI on Windows -The following tools are required to build and run the [GUI](abbr:Graphical User Interface). +The following tools are required to build the HandBrake GUI. - [Microsoft Visual Studio Community](https://www.visualstudio.com/vs/community/) -- A Git client - - [Source Tree](https://www.sourcetreeapp.com) (recommended) - - Client included with Visual Studio 2022 or later -- `hb.dll` (see the LibHB build instructions preceding these, or download from [https://github.com/HandBrake/handbrake-snapshots/)) +- Git client to download the HandBrake source code + - [Atlassian Sourcetree](https://www.sourcetreeapp.com) (graphical interface, recommended) + - [Git for Windows](https://git-scm.com/install/windows) (command line interface) + - Client included with Visual Studio + +Begin by downloading and installing the required tools. + +Clone the HandBrake repository at `https://github.com/HandBrake/HandBrake.git` using your Git client. If you are using Git for Windows, the command is: + + git clone https://github.com/HandBrake/HandBrake.git + +Navigate to the `win\CS` folder and open the `HandBrake.sln` solution file in Visual Studio. In the Visual Studio Solution Explorer pane, right-click on the `HandBrakeWPF` project and choose "Set as Startup Project". + +To build the HandBrake GUI, choose Build > Build Solution from the Visual Studio main menu. The build process will take a few moments. +When completed, navigate to the `win\CS\HandBrakeWPF\bin` folder. The `Debug` folder contains the built HandBrake GUI[^solution-configuration]. Copy the LibHB core library `hb.dll` file you previously downloaded or built to the `Debug` folder. -Clone `https://github.com/HandBrake/HandBrake.git` using your git client. +Now that you have completed building HandBrake, you can rename the folder to whatever you prefer, e.g., `HandBrake`, and copy or move it to another location on your system if desired. If you want to run multiple isolated copies of HandBrake on your machine, rename the `portable.ini.template` file inside the folder to `portable.ini`. -Source code for the GUI resides in the `win\CS` folder and the solution file is named `HandBrake.sln`. Make sure HandBrakeWPF is set as the startup project in the Solution Explorer by right-clicking the name and selecting "Set as startup project". +Open `HandBrake.exe` to launch HandBrake. -To build the GUI, select Build Solution from the Build menu. +## Troubleshooting -When complete, locate the output folder where `HandBrake.exe` is created (typically in `win\CS\HandBrakeWPF\bin\...`, depending on the selected build profile). Copy `hb.dll` to this folder. This completes the build process. +If you encounter any issues, someone may be able to help via HandBrake's [Community support](../help/community-support.markdown) channels. -[^fdk-aac-license]: The FDK AAC encoder is only provided in source code form and is not fully compatible with the GNU General Public License Version 2 used by HandBrake. Builds including FDK AAC must be for personal use only and may not be distributed. Do not share the build product with others. +[^solution-configuration]: If you changed the solution configuration from `Debug` to `Release` in Visual Studio, the `Release` folder contains the built HandBrake GUI. diff --git a/source/docs/en/latest/developer/install-dependencies-fedora.markdown b/source/docs/en/latest/developer/install-dependencies-fedora.markdown index 91094402..2e33f4f6 100644 --- a/source/docs/en/latest/developer/install-dependencies-fedora.markdown +++ b/source/docs/en/latest/developer/install-dependencies-fedora.markdown @@ -16,7 +16,7 @@ License_URL: https://handbrake.fr/docs/license.html Installing dependencies on Fedora ================================= -The following instructions are for [Fedora](https://fedoraproject.org) 42 and 43. +The following instructions are for [Fedora](https://fedoraproject.org) 43 and 44. Basic requirements to run commands: @@ -68,9 +68,10 @@ Additional dependencies not available in the base repository: Dolby Vision dependencies (optional): +- openssl-devel - rustup -Intel Quick Sync Video dependencies (optional): +Intel Quick Sync Video and VAAPI dependencies (optional): - libva-devel - libdrm-devel @@ -99,12 +100,11 @@ Install the [RPM Fusion](http://rpmfusion.org) Free repository and related addit To build with Dolby Vision support, install the Rust dependencies. - sudo dnf5 install rustup + sudo dnf5 install openssl-devel rustup rustup-init -y && source "~/.cargo/env" - rustup target add x86_64-pc-windows-gnu cargo install cargo-c -To build with Intel Quick Sync Video support, install the QSV dependencies. +To build with Intel Quick Sync Video and VAAPI support, install the VAAPI dependencies. sudo dnf5 install libva-devel libdrm-devel diff --git a/source/docs/en/latest/developer/install-dependencies-ubuntu.markdown b/source/docs/en/latest/developer/install-dependencies-ubuntu.markdown index 0af0b478..c2750757 100644 --- a/source/docs/en/latest/developer/install-dependencies-ubuntu.markdown +++ b/source/docs/en/latest/developer/install-dependencies-ubuntu.markdown @@ -16,30 +16,98 @@ License_URL: https://handbrake.fr/docs/license.html Installing dependencies on Ubuntu ================================= -The following instructions are for [Ubuntu](https://www.ubuntu.com) 22.04 (Jammy Jellyfish). +The following instructions are for [Ubuntu](https://www.ubuntu.com) 24.04 Noble Numbat and 26.04 Resolute Racoon. Basic requirements to run commands: - sudo (for normal user accounts) +Dependencies: + +- autoconf +- automake +- build-essential +- cmake +- git +- libass-dev +- libbz2-dev +- libfontconfig-dev +- libfreetype-dev +- libfribidi-dev +- libharfbuzz-dev +- libjansson-dev +- liblzma-dev +- libmp3lame-dev +- libnuma-dev +- libogg-dev +- libopus-dev +- libsamplerate0-dev +- libspeex-dev +- libssl-dev +- libtheora-dev +- libtool +- libtool-bin +- libturbojpeg0-dev +- libvorbis-dev +- libvpx-dev +- libx11-dev +- libx264-dev +- libxml2-dev +- m4 +- make +- meson +- nasm +- ninja-build +- patch +- pkg-config +- zlib1g-dev + +Dolby Vision dependencies (optional): + +- rustup + +Intel Quick Sync Video and VAAPI dependencies (optional): + +- libva-dev +- libdrm-dev + +Nvidia NVENC/NVDEC dependencies (optional): + +- clang +- llvm + +Graphical interface dependencies: + +- appstream +- desktop-file-utils +- gettext +- gstreamer1.0-libav +- gstreamer1.0-plugins-good +- libgstreamer-plugins-base1.0-dev +- libgtk-4-dev + Install dependencies. sudo apt-get update - sudo apt-get install autoconf automake build-essential cmake git libass-dev libbz2-dev libfontconfig-dev libfreetype-dev libfribidi-dev libharfbuzz-dev libjansson-dev liblzma-dev libmp3lame-dev libnuma-dev libogg-dev libopus-dev libsamplerate0-dev libspeex-dev libtheora-dev libtool libtool-bin libturbojpeg0-dev libvorbis-dev libx264-dev libxml2-dev libvpx-dev m4 make meson nasm ninja-build patch pkg-config tar zlib1g-dev curl libssl-dev clang + sudo apt-get install autoconf automake build-essential cmake git libass-dev libbz2-dev libfontconfig-dev libfreetype-dev libfribidi-dev libharfbuzz-dev libjansson-dev liblzma-dev libmp3lame-dev libnuma-dev libogg-dev libopus-dev libsamplerate0-dev libspeex-dev libssl-dev libtheora-dev libtool libtool-bin libturbojpeg0-dev libvorbis-dev libvpx-dev libx11-dev libx264-dev libxml2-dev m4 make meson nasm ninja-build patch pkg-config zlib1g-dev -For libdovi, you will also need rust, cargoc and associated dependencies: +To build with Dolby Vision support, install the Rust dependencies. - curl https://sh.rustup.rs -sSf | sh - source "$HOME/.cargo/env" + sudo apt-get install rustup + rustup toolchain install "stable-$(uname -m)-unknown-linux-gnu" + rustup default "stable-$(uname -m)-unknown-linux-gnu" cargo install cargo-c - rustup target add x86_64-pc-windows-gnu -To build with Intel Quick Sync Video support, install the QSV dependencies. +To build with Intel Quick Sync Video and VAAPI support, install the VAAPI dependencies. sudo apt-get install libva-dev libdrm-dev +To build with Nvidia NVENC/NVDEC support, install the CUDA LLVM toolchain dependencies. + + sudo apt-get install clang llvm + To build the GTK [GUI](abbr:Graphical User Interface), install the graphical interface dependencies. sudo apt-get install appstream desktop-file-utils gettext gstreamer1.0-libav gstreamer1.0-plugins-good libgstreamer-plugins-base1.0-dev libgtk-4-dev -Ubuntu is now prepared to build HandBrake. See [Building HandBrake for Linux](build-linux.markdown) for further instructions. +Ubuntu is now prepared to build HandBrake. See [Building HandBrake for Linux](build-linux.markdown) for further instructions, or if you intend to cross-compile HandBrake for Windows, see [Building HandBrake for Windows](build-windows.markdown).