Skip to content

docs: Update Fedora and Ubuntu, Linux and Windows build guides. #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bradleysepos merged 1 commit into from
Aug 20, 2026
+212 −108
Merged

docs: Update Fedora and Ubuntu, Linux and Windows build guides. #267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 34 additions & 20 deletions source/docs/en/latest/developer/build-linux.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
172 changes: 97 additions & 75 deletions source/docs/en/latest/developer/build-windows.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 5 additions & 5 deletions source/docs/en/latest/developer/install-dependencies-fedora.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
Loading
Loading