Quick Start Guide

Build and run SerenityOS on your machine using QEMU with this step-by-step guide

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:

Ubuntu / Debian

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

Arch Linux / Manjaro

Install Dependencies

sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip

Optional packages:

• fuse2fs for building images without root
• clang llvm llvm-libs for building with Clang

Windows (WSL2)

You must use WSL2 to build SerenityOS on Windows. Please refer to the Windows build guide for detailed instructions.

Once WSL2 is set up, follow the Ubuntu/Debian instructions above.

macOS

See the macOS build instructions for detailed setup steps.

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

Build is broken after git pull

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.

fusermount error during build

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.

Toolchain is outdated

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