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 packagesC++26 capable compiler (g++-14 or clang-17 minimum)
Debian/Ubuntu
Arch Linux/Manjaro
Fedora
openSUSE
macOS
NixOS/Nix
OpenIndiana
Haiku
Windows
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
sudo pacman -S --needed base-devel cmake libgl ninja qt6-base \ qt6-tools qt6-wayland ccache
sudo dnf install cmake libglvnd-devel ninja-build qt6-qtbase-devel \ qt6-qttools-devel qt6-qtwayland-devel ccache
sudo zypper install cmake libglvnd-devel ninja qt6-base-devel \ qt6-tools-devel qt6-wayland-devel ccache
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: nix develop .#ladybird # With custom entrypoint nix develop .#ladybird --command bash
Legacy nix-shell: OpenIndiana’s GCC 11 is too old. Use Clang 17 instead.
pfexec pkg install cmake ninja clang-17 libglvnd qt6
pkgman install cmake ninja cmd:python3 qt6_base_devel \ qt6_tools_devel openal_devel
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
Debug with GDB
./Meta/serenity.sh run lagom ladybird
Browser Chrome The build uses different browser chromes depending on platform:
AppKit - Native macOS chrome
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:
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
Build
cmake --build Build/ladybird
Run
Using Ninja
Direct (Linux)
Direct (macOS)
ninja -C Build/ladybird run
Debug mode: ninja -C Build/ladybird debug
./Build/ladybird/bin/Ladybird
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
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.
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
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
Run Ladybird
./Meta/serenity.sh run lagom ladybird
Attach debugger
In CLion:
Run → Attach to Process Filter for WebContent
Attach
For layout/rendering issues, attach to the WebContent process.
Xcode (macOS)
Generate Xcode project
cmake -GXcode -S Meta/Lagom -B Build/lagom \ -DBUILD_LAGOM=ON -DENABLE_LAGOM_LADYBIRD=ON
cmake -GXcode -S Ladybird -B Build/ladybird
Open in Xcode
open Build/lagom/ladybird.xcodeproj # or open Build/ladybird/ladybird.xcodeproj
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.
Ensure Qt6 development packages are installed: # Debian/Ubuntu sudo apt install qt6-base-dev qt6-tools-dev-tools # macOS brew install qt
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+: Or install Homebrew compiler: Next Steps
Main Project Visit the official Ladybird browser project
Advanced Build Options Explore CMake options and customization
