Skip to main content
The first build will take some time as it downloads database files and builds the cross-compiler toolchain. Subsequent builds will be much faster.

​
Prerequisites

SerenityOS supports building on Linux, macOS, Windows (with WSL2), and many other *nix systems. Choose your platform below:

​
Install Dependencies

sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo libssl-dev zlib1g-dev
Optional: Install fuse2fs for building images without root privileges.

​
Install GCC 14 or Clang 17+

A host compiler that supports C++26 features is required. The newer the better.

​
Option 1: GCC 14

GCC 14 is available in Ubuntu 24.04 (Noble) and later:
sudo apt update
sudo apt install gcc-14 g++-14
For older versions, use the ubuntu-toolchain-r/test PPA.

​
Option 2: Clang 17+

Recent versions of Clang are available in the LLVM apt repositories:
sudo apt install libclang-19-dev clang-19 llvm-19 llvm-19-dev

​
QEMU 6.2 or Later

QEMU 6.2 is available in Ubuntu 22.04. For earlier versions, build QEMU from the toolchain:
Toolchain/BuildQemu.sh
You may need additional packages to build QEMU:
sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev

​
CMake 3.25.0 or Later

The build scripts will automatically build CMake from source if your version is older than 3.25.x.
If you previously used an older CMake version, remove the cache files:
rm Build/*/CMakeCache.txt

​
Build and Run

1

Clone the Repository

First, clone the SerenityOS repository:
git clone https://github.com/SerenityOS/serenity.git
cd serenity
2

Build and Launch SerenityOS

Run the following command to build and run SerenityOS:
Meta/serenity.sh run
This single command will:
  • Download required database files (first time only)
  • Build the SerenityOS cross-compiler toolchain (first time only)
  • Compile all of SerenityOS
  • Install built files into Build/<architecture>/Root
  • Build a disk image
  • Start SerenityOS using QEMU
The chosen architecture defaults to your host architecture. Supported architectures are x86_64, aarch64, and riscv64.
3

Log In to SerenityOS

When SerenityOS boots, log in with the default credentials:
  • Username: anon
  • Password: foo
By default, the anon user can become root without a password as a development convenience. To prevent this, remove anon from the wheel group.

​
Build Without Running

If you want to test whether your code changes compile without running the VM: 
Meta/serenity.sh build

​
Additional Commands

The serenity.sh script provides many other commands. Run it without arguments to see the full list: 
Meta/serenity.sh

​
Troubleshooting

If the build breaks after pulling changes:
  1. Rebuild the toolchain if prompted
  2. Try with a clean repository if toolchain rebuild doesn’t help
  3. Ask for help in the #build-problems channel on Discord
If it builds on CI, it should build for you too.
If you see an error like fusermount: failed to open /etc/mtab: No such file or directory:
sudo ln -sv /proc/self/mounts /etc/mtab
This creates the missing symlink that fuse2fs requires.
When updating to a newer compiler, you may need to rebuild the toolchain. See the troubleshooting guide for details.

​
Installing Ports

To add a package from the ports collection (for example, curl):
1

Navigate to Port Directory

cd Ports/curl
2

Run the Package Script

./package.sh
The source code will be downloaded and the package will be built.
3

Launch SerenityOS

The next time you start SerenityOS, the port will be available.

​
Port Dependencies

Some ports require additional dependencies on your host system. Common requirements include: 
# Common dependencies
sudo apt install autoconf automake bison flex gettext gperf help2man \
  imagemagick libgpg-error-dev libtool lzip meson nasm \
  python3-packaging qt6-base-dev rename zip
Special port dependencies:
  • file (version 5.44 exactly, for file)
  • libpython3-dev (for boost)
  • lua (for luarocks)
  • openjdk-17-jdk (to compile OpenJDK)
  • p7zip-full (for msttcorefonts)
  • rake (to build mruby)
You may need a symlink from /usr/bin/python to /usr/bin/python3 as some ports depend on python existing, most notably ninja.

​
Next Steps

Advanced Build Instructions

Learn about advanced build options and customization

Contributing Guide

Start contributing to SerenityOS

FAQ

Find answers to common questions

Documentation

Browse technical documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us