Building Ladybird Browser

Build the Ladybird web browser from SerenityOS

The Ladybird browser project has moved to LadybirdBrowser/ladybird. This version is kept as a developer convenience for testing LibWeb and LibJS libraries included with SerenityOS.

Prerequisites

Ladybird requires:

• Qt6 development packages
• C++26 capable compiler (g++-14 or clang-17 minimum)

Debian/Ubuntu

sudo apt install build-essential cmake libgl1-mesa-dev ninja-build \
  qt6-base-dev qt6-tools-dev-tools ccache

For Ubuntu 20.04 and above, install Qt6 Wayland:

sudo apt install qt6-wayland

Arch Linux/Manjaro

sudo pacman -S --needed base-devel cmake libgl ninja qt6-base \
  qt6-tools qt6-wayland ccache

Fedora

sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel \
  qt6-qttools-devel qt6-qtwayland-devel ccache

openSUSE

sudo zypper install cmake libglvnd-devel ninja qt6-base-devel \
  qt6-tools-devel qt6-wayland-devel ccache

macOS

Xcode 14.3 or later is required. Earlier 14.x versions may crash during build.

xcode-select --install
brew install cmake ninja ccache

For Qt chrome on macOS:

brew install qt

NixOS/Nix

nix develop .#ladybird

# With custom entrypoint
nix develop .#ladybird --command bash

Legacy nix-shell:

nix-shell Ladybird

OpenIndiana

OpenIndiana’s GCC 11 is too old. Use Clang 17 instead.

pfexec pkg install cmake ninja clang-17 libglvnd qt6

Haiku

pkgman install cmake ninja cmd:python3 qt6_base_devel \
  qt6_tools_devel openal_devel

Windows

WSL2/WSLg are preferred. MinGW/MSYS2 and native Windows builds are not officially supported.

Follow the WSL2 setup guide, then use the Linux instructions.

Building with serenity.sh

The simplest way to build Ladybird:

Run Ladybird

./Meta/serenity.sh run lagom ladybird

Browser Chrome

The build uses different browser chromes depending on platform:

macOS

AppKit - Native macOS chrome

Linux/Others

Qt - Cross-platform Qt chrome

Enabling Qt Chrome

To build the Qt chrome on platforms where it’s not default:

cmake -S Meta/Lagom -B Build/lagom -DENABLE_QT=ON

To disable Qt chrome:

cmake -S Meta/Lagom -B Build/lagom -DENABLE_QT=OFF

Disabling Ladybird

Running Ladybird from serenity.sh changes the CMake cache to always build LibWeb and Ladybird for Lagom.

To restore the default behavior (only build code generators and tools):

cmake -S Meta/Lagom -B Build/lagom \
  -DENABLE_LAGOM_LADYBIRD=OFF \
  -DENABLE_LAGOM_LIBWEB=OFF \
  -DBUILD_LAGOM=OFF

Custom CMake Build

For packaging or standalone builds:

1. Configure build

   cmake -GNinja -S Ladybird -B Build/ladybird
   

   You may need to specify a suitable compiler:

   cmake -GNinja -S Ladybird -B Build/ladybird \
     -DCMAKE_CXX_COMPILER=clang++-19 \
     -DCMAKE_C_COMPILER=clang-19
   
2. Build

   cmake --build Build/ladybird
   
3. Run

   Using Ninja

   ninja -C Build/ladybird run
   

   Debug mode:

   ninja -C Build/ladybird debug
   

   Direct (Linux)

   ./Build/ladybird/bin/Ladybird
   

   Direct (macOS)

   open -W --stdout $(tty) --stderr $(tty) \
     ./Build/ladybird/bin/Ladybird.app
   
   # With arguments:
   open -W --stdout $(tty) --stderr $(tty) \
     ./Build/ladybird/bin/Ladybird.app \
     --args https://ladybird.dev
   
4. Install (optional)

   cmake --install Build/ladybird --prefix /usr/local
   

   Install rules are defined in Ladybird/cmake/InstallRules.cmake.

Resource Files

Ladybird requires resource files from serenity/Base/res for icons, fonts, and theming.

The serenity.sh script handles resource paths automatically. For custom builds:

• Use ninja rules (ninja run, ninja debug)
• Or install Ladybird with CMake install rules
• Or manually set resource paths when running the binary

Experimental GN Build

The GN build is experimental and maintained on a best-effort basis.

Benefits:

• More compact ninja rules
• Potentially faster builds
• Support for host and cross-targets in the same build directory

See the GN build instructions for details.

Platform-Specific Notes

OpenIndiana

Set CMake variables for Qt6 and Clang:

CMAKE_PREFIX_PATH=/usr/lib/qt/6.2/lib/amd64/cmake \
  cmake -GNinja -S Ladybird -B Build/ladybird \
  -DCMAKE_C_COMPILER=/usr/bin/clang \
  -DCMAKE_CXX_COMPILER=/usr/bin/clang++

cmake --build Build/ladybird

# Run with XDG_RUNTIME_DIR set
XDG_RUNTIME_DIR=/var/tmp ninja -C Build/ladybird run

Replace 6.2 with your installed Qt version.

Haiku

No special configuration needed:

cmake -GNinja -S Ladybird -B Build/ladybird
cmake --build Build/ladybird
ninja -C Build/ladybird run

Debugging

CLion

1. Build with debug symbols

   Edit Meta/CMake/lagom_compile_options.cmake:

   • Change -O2 to -O0
   • macOS: Change -g1 to -g
   • Linux: Change -g1 to -ggdb3
2. Run Ladybird

   ./Meta/serenity.sh run lagom ladybird
   
3. Attach debugger

   In CLion:

   1. Run → Attach to Process
   2. Filter for WebContent
   3. Attach

   For layout/rendering issues, attach to the WebContent process.

Xcode (macOS)

1. Generate Xcode project

   Compatible with serenity.sh

   cmake -GXcode -S Meta/Lagom -B Build/lagom \
     -DBUILD_LAGOM=ON -DENABLE_LAGOM_LADYBIRD=ON
   

   Standalone

   cmake -GXcode -S Ladybird -B Build/ladybird
   
2. Open in Xcode

   open Build/lagom/ladybird.xcodeproj
   # or
   open Build/ladybird/ladybird.xcodeproj
   
3. Create scheme

   Create a scheme for the Ladybird app bundle target.

Troubleshooting

Build fails with C++26 errors

Verify compiler version:

g++ --version  # Should be 14+
clang++ --version  # Should be 17+

Install newer compiler if needed.

Qt6 not found

Ensure Qt6 development packages are installed:

# Debian/Ubuntu
sudo apt install qt6-base-dev qt6-tools-dev-tools

# macOS
brew install qt

Resource files missing

Use the ninja rules:

ninja -C Build/ladybird run

Or ensure serenity/Base/res is accessible to the binary.

Xcode 14.2 or older crashes

Update to Xcode 14.3+:

xcode-select --install

Or install Homebrew compiler:

brew install llvm@18

Next Steps

Main Project

Visit the official Ladybird browser project

Advanced Build Options

Explore CMake options and customization