> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/LadybirdBrowser/ladybird/llms.txt
> Use this file to discover all available pages before exploring further.

# Build instructions

> Complete build instructions for Ladybird browser across all supported platforms

## Build prerequisites

Qt6 development packages, nasm, additional build tools, and a C++23 capable compiler are required.

A Rust toolchain is also required for building the JavaScript engine. You can install it via [rustup](https://rustup.rs/) or your system's package manager.

<Info>
  We currently use gcc-14 and clang-21 in our CI pipeline. If these versions are not available on your system, see `Meta/find_compiler.py` for the minimum compatible version.
</Info>

**CMake 3.30 or newer must be available in \$PATH.**

***

## Platform-specific dependencies

<Tabs>
  <Tab title="Debian/Ubuntu">
    <Steps>
      <Step title="Install base dependencies">
        ```bash theme={null}
        sudo apt install autoconf autoconf-archive automake build-essential ccache cmake curl fonts-liberation2 git libdrm-dev libgl1-mesa-dev libtool nasm ninja-build pkg-config python3-venv qt6-base-dev qt6-tools-dev-tools qt6-wayland tar unzip zip
        ```
      </Step>

      <Step title="Install CMake 3.30 or newer">
        <Note>This repository is Ubuntu-only</Note>

        ```bash theme={null}
        # Add Kitware GPG signing key
        wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null

        # Use the key to authorize an entry for apt.kitware.com in apt sources list
        echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/kitware.list

        # Update apt package list and install cmake
        sudo apt update -y && sudo apt install cmake -y
        ```
      </Step>

      <Step title="Install a C++23-capable compiler">
        <Tabs>
          <Tab title="Clang (Recommended)">
            Install clang from [LLVM's apt repository](https://apt.llvm.org/):

            ```bash theme={null}
            # Add LLVM GPG signing key
            sudo wget -O /usr/share/keyrings/llvm-snapshot.gpg.key https://apt.llvm.org/llvm-snapshot.gpg.key

            # Use the key to authorize an entry for apt.llvm.org in apt sources list
            echo "deb [signed-by=/usr/share/keyrings/llvm-snapshot.gpg.key] https://apt.llvm.org/$(lsb_release -sc)/ llvm-toolchain-$(lsb_release -sc)-21 main" | sudo tee -a /etc/apt/sources.list.d/llvm.list

            # Update apt package list and install clang and associated packages
            sudo apt update -y && sudo apt install clang-21 clangd-21 clang-tools-21 clang-format-21 clang-tidy-21 lld-21 -y
            ```
          </Tab>

          <Tab title="GCC (Alternative)">
            Install gcc from [Ubuntu Toolchain PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test):

            ```bash theme={null}
            sudo add-apt-repository ppa:ubuntu-toolchain-r/test
            sudo apt update && sudo apt install g++-14 libstdc++-14-dev
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Install audio support (optional)">
        ```bash theme={null}
        sudo apt install libpulse-dev
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Arch Linux/Manjaro">
    ```bash theme={null}
    sudo pacman -S --needed autoconf-archive base-devel ccache cmake curl git less libgl nasm ninja python qt6-base qt6-tools ttf-liberation tar unzip zip
    ```

    Optionally, install the PulseAudio headers for audio playback support:

    ```bash theme={null}
    sudo pacman -S libpulse
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    sudo dnf install autoconf-archive automake ccache cmake curl git libdrm-devel liberation-sans-fonts libglvnd-devel libtool nasm ninja-build patchelf perl-FindBin perl-IPC-Cmd perl-lib perl-Time-Piece qt6-qtbase-devel qt6-qttools-devel qt6-qtwayland-devel tar unzip zip zlib-ng-compat-static
    ```
  </Tab>

  <Tab title="openSUSE">
    ```bash theme={null}
    sudo zypper install autoconf-archive automake ccache cmake curl gcc14 gcc14-c++ git liberation-fonts libglvnd-devel libtool nasm ninja qt6-base-devel qt6-tools-devel qt6-wayland-devel tar unzip zip
    ```

    <Warning>
      If base repository packages are flagged as having an out-of-date version during the build process, you may need to add the `devel:tools:building` repository.
    </Warning>

    For Leap 15.6:

    ```bash theme={null}
    sudo zypper addrepo https://download.opensuse.org/repositories/devel:tools:building/15.6/devel:tools:building.repo
    sudo zypper refresh
    ```

    Install audio support:

    ```bash theme={null}
    sudo zypper install libpulse-devel
    ```
  </Tab>

  <Tab title="Void Linux">
    ```bash theme={null}
    sudo xbps-install -Su # (optional) ensure packages are up to date
    sudo xbps-install -S git bash gcc python3 curl cmake libtool zip unzip linux-headers make pkg-config autoconf automake autoconf-archive nasm MesaLib-devel ninja qt6-base-devel qt6-tools-devel qt6-wayland-devel
    ```
  </Tab>

  <Tab title="macOS">
    Xcode 15 or clang from homebrew is required to successfully build ladybird.

    ```bash theme={null}
    xcode-select --install
    brew install autoconf autoconf-archive automake ccache cmake libtool nasm ninja pkg-config
    ```

    If you wish to use clang from homebrew instead:

    ```bash theme={null}
    brew install llvm@21
    ```

    If you also plan to use the Qt UI on macOS:

    ```bash theme={null}
    brew install qt
    ```

    <Tip>
      It is recommended to add your terminal application (i.e. Terminal.app or iTerm.app) to the system list of developer tools. This will reduce slow startup time of freshly compiled binaries, due to macOS validating the binary on its first run.

      This can be done in the "Developer Tools" section of the "Privacy & Security" system settings.
    </Tip>
  </Tab>

  <Tab title="Windows">
    ### WSL2 (Recommended)

    WSL2 is the supported way to build Ladybird on Windows. A native build is also possible, however it is still experimental.

    <Steps>
      <Step title="Create a WSL2 environment">
        Use one of the Linux distros listed above. Ubuntu or Fedora is recommended.
      </Step>

      <Step title="Install the required packages">
        Install the required packages for the selected Linux distro in the WSL2 environment.
      </Step>
    </Steps>

    <Warning>
      WSL1 is known to have issues. Please use WSL2. MinGW/MSYS2 are not supported.
    </Warning>

    ### Clang-CL (Experimental)

    <Note>There are still windows specific issues and the functionality is limited.</Note>

    Install pkg-config using Chocolatey:

    ```bash theme={null}
    choco install pkgconfiglite -y
    ```

    Build using ladybird.py in a VS command prompt:

    ```bash theme={null}
    py Meta\ladybird.py build
    ```
  </Tab>

  <Tab title="Android">
    On a Unix-like platform, install the prerequisites for that platform and then see the Android Studio guide.

    Or, download a version of Gradle >= 8.0.0, and run the `gradlew` program in `UI/Android`.
  </Tab>

  <Tab title="FreeBSD">
    ```bash theme={null}
    pkg install autoconf-archive automake autoconf bash cmake curl gmake gn libdrm libtool libxcb libxkbcommon libX11 libXrender libXi nasm ninja patchelf pkgconf python3 qt6-base unzip zip
    ```
  </Tab>

  <Tab title="NixOS">
    A Nix development shell is maintained in the [nix-environments](https://github.com/nix-community/nix-environments/) repository.

    If you encounter any problems building with Nix, please create an issue there.
  </Tab>
</Tabs>

***

## Build steps

### Using ladybird.py

The simplest way to build and run ladybird is via the `ladybird.py` script:

```bash theme={null}
# From /path/to/ladybird
./Meta/ladybird.py run
```

<Tabs>
  <Tab title="Standard build">
    ```bash theme={null}
    ./Meta/ladybird.py run
    ```
  </Tab>

  <Tab title="macOS with homebrew clang">
    ```bash theme={null}
    CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++ ./Meta/ladybird.py run
    ```
  </Tab>

  <Tab title="Debug build">
    ```bash theme={null}
    BUILD_PRESET=Debug ./Meta/ladybird.py run
    ```

    <Info>Note that debug symbols are available in both Release and Debug builds.</Info>
  </Tab>

  <Tab title="With gdb">
    ```bash theme={null}
    ./Meta/ladybird.py gdb ladybird
    ```
  </Tab>
</Tabs>

<Tip>
  If you want to run other applications, such as the JS REPL or the WebAssembly REPL, specify an executable with `./Meta/ladybird.py run <executable_name>`.
</Tip>

### The user interfaces

Ladybird will be built with one of the following browser frontends, depending on the platform:

* **AppKit** - The native UI on macOS
* **Qt** - The UI used on all other platforms
* **Android UI** - The native UI on Android

The Qt UI is available on platforms where it is not the default as well (except on Android). To build the Qt UI, install the Qt dependencies for your platform, and enable the Qt UI via CMake:

```bash theme={null}
# From /path/to/ladybird
cmake --preset default -DENABLE_QT=ON
```

To re-disable the Qt UI, run the above command with `-DENABLE_QT=OFF`.

### Custom CMake build directory

The script `Meta/ladybird.py` and the default preset in `CMakePresets.json` both define a build directory of `Build/release`. For distribution purposes, or when building multiple configurations, it may be useful to create a custom CMake build directory.

```bash theme={null}
cmake --preset default -B MyBuildDir
# optionally, add -DCMAKE_CXX_COMPILER=<suitable compiler> -DCMAKE_C_COMPILER=<matching c compiler>
cmake --build --preset default MyBuildDir
ninja -C MyBuildDir run-ladybird
```

<Info>
  The install rules in `UI/cmake/InstallRules.cmake` define which binaries and libraries will be installed into the configured CMAKE\_PREFIX\_PATH or path passed to `cmake --install`.
</Info>

### Building with limited system memory

The default build mode will run as many build steps in parallel as possible, which includes link steps; this may be an issue for users with limited system memory.

If you wish to reduce the number of parallel link jobs, you may use the `LAGOM_LINK_POOL_SIZE` cmake option:

```bash theme={null}
cmake --preset default -B MyBuildDir -DLAGOM_LINK_POOL_SIZE=2
```

### Running manually

The `Meta/ladybird.py` script will execute the `run-ladybird` and `debug-ladybird` custom targets. If you don't want to use the script, you can run the following commands:

<CodeGroup>
  ```bash gdb theme={null}
  ninja -C Build/release debug-ladybird
  ```

  ```bash Linux theme={null}
  ./Build/release/bin/Ladybird
  ```

  ```bash macOS theme={null}
  open -W --stdout $(tty) --stderr $(tty) ./Build/release/bin/Ladybird.app

  # Or to launch with arguments:
  open -W --stdout $(tty) --stderr $(tty) ./Build/release/bin/Ladybird.app --args https://ladybird.dev
  ```
</CodeGroup>

***

## Resource files

Ladybird requires resource files from the `ladybird/Base/res` directory in order to properly load icons, fonts, and other theming information. These files are copied into the build directory by special CMake rules.

<Info>
  The expected location of resource files can be tweaked by packagers using the standard `CMAKE_INSTALL_DATADIR` variable. `CMAKE_INSTALL_DATADIR` is expected to be a path relative to `CMAKE_INSTALL_PREFIX`. If it is not, things will break.
</Info>

***

## Debugging

### Debugging with CLion

Ladybird should be built with debug symbols first. This can be done by adding `-DCMAKE_BUILD_TYPE=Debug` to the cmake command line, or selecting the Build Type Debug in the CLion CMake profile.

After running Ladybird with `./Meta/ladybird.py run ladybird`, you can use **Run → Attach to Process** in CLion to connect. If debugging layout or rendering issues, filter the listing for `WebContent` and attach to that.

Now breakpoints, stepping and variable inspection will work.

### Debugging with Xcode or Instruments on macOS

If all you want to do is use Instruments, then an Xcode project is not required.

Simply run the `ladybird.py` script as normal, and then make sure to codesign the Ladybird binary with the proper entitlements to allow Instruments to attach to it:

```bash theme={null}
./Meta/ladybird.py build
ninja -C Build/release apply-debug-entitlements
# or
codesign -s - -v -f --entitlements Meta/debug.plist Build/release/bin/Ladybird.app
```

Now you can open the Instruments app and point it to the Ladybird app bundle.

<Warning>
  Building the project with Xcode is not supported. The Xcode project generated by CMake does not properly execute custom targets, and does not handle all target names in the project.
</Warning>

***

## Common build errors

### Unable to find a build program corresponding to "Ninja"

This error message is a red herring. We use vcpkg to manage our third-party dependencies, and this error is logged when something went wrong building those dependencies.

The output in your terminal will vary depending on what exactly went wrong, but it should look something like:

```
error: building skia:x64-linux failed with: BUILD_FAILED
Elapsed time to handle skia:x64-linux: 1.6 s

-- Running vcpkg install - failed
CMake Error at Toolchain/Tarballs/vcpkg/scripts/buildsystems/vcpkg.cmake:899 (message):
  vcpkg install failed.  See logs for more information:
  Build/release/vcpkg-manifest-install.log
```

<Tip>
  If the error is not immediately clear from the terminal output, be sure to check the specified `vcpkg-manifest-install.log` for more information.
</Tip>

***

## Experimental GN build

There is an experimental GN build for Ladybird. It is not officially supported, but it is kept up to date on a best-effort basis by interested contributors. See the GN build instructions in `Meta/gn/README.md` for more information.

In general, the GN build organizes ninja rules in a more compact way than the CMake build, and it may be faster on some systems. GN also allows building host and cross-targets in the same build directory, which is useful for managing dependencies on host tools when cross-compiling to other platforms.