Skip to main content
QEMU is the default and recommended way to run SerenityOS. The build system includes automated QEMU support for easy testing and development.

​
Prerequisites

​
QEMU 6.2 or later

Version 6.2 of QEMU is available in Ubuntu 22.04. On earlier versions of Ubuntu, you can build the recommended version of QEMU as provided by the toolchain.
1

Install QEMU dependencies

Install the required development packages:
sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev
2

Build QEMU from toolchain

If your distribution’s QEMU version is older than 6.2:
Toolchain/BuildQemu.sh

​
Running SerenityOS

The simplest way to build and run SerenityOS in QEMU: 
Meta/serenity.sh run
This command will:
  • 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.

​
First Build

The first time you run the build command, it will:
  • Download required database files from the internet
  • Build the SerenityOS cross-compiler toolchain
Subsequent builds will be much faster as these steps only need to be done once.

​
Default Credentials

By default, the anon user account’s password is: foo
The anon user can become root without a password by default as a development convenience. To prevent this, remove anon from the wheel group.

​
Build Options

​
Selecting an Architecture

Force a build for a specific architecture: 
SERENITY_ARCH=aarch64 Meta/serenity.sh run
Supported values: x86_64, aarch64, riscv64

​
Build Only (No VM)

To test compilation without running the VM: 
Meta/serenity.sh build

​
Kernel Command Line Parameters

Pass additional kernel parameters: 
Meta/serenity.sh run x86_64 smp=on

​
QEMU Integration Features

​
SPICE Integration

SPICE provides enhanced clipboard and display integration.
1

Build QEMU via toolchain

Toolchain/BuildQemu.sh
2

Install virt-viewer

On Ubuntu 23.04+:
sudo apt-get install virt-viewer
For earlier versions, you may need to build virt-viewer 8.0 from source.
3

Enable SPICE and run

export SERENITY_SPICE=1
Meta/serenity.sh run

​
File Transfer from QEMU

​
Method 1: WebServer

Serenity has a built-in web server accessible from your host:
1

Start WebServer in SerenityOS

In the SerenityOS terminal:
ws .
2

Access from host browser

Open localhost:8000 in your host machine’s browser.
Some browsers download unrecognized files as plain text. Use wget to download files as-is instead.

​
Method 2: Mount the Disk Image

On *nix systems or inside WSL: 
cd "Build/${SERENITY_ARCH}"
mkdir mnt
sudo mount -t ext2 _disk_image mnt

​
Method 3: Archiving Tool

Some archiving tools like 7-Zip can directly open ext2 images like Serenity’s _disk_image.
For WSL users: Access the WSL drive in Windows Explorer via \\wsl$\<distro name>\<path to serenity directory>.

​
Method 4: OpenSSH and SFTP

1

Setup OpenSSH server on host

Configure OpenSSH server on your host system (Windows or Linux).
2

Build OpenSSH port in SerenityOS

cd Ports/openssh
./package.sh
cd ../..
Meta/serenity.sh run
3

Connect via SFTP

From within SerenityOS:
sftp [email protected]
Use commands like ls, cd, put [filename], get [filename], and quit.

​
Debugging

​
GDB Remote Session

Start SerenityOS with GDB attached: 
Meta/serenity.sh gdb x86_64 smp=on -ex 'hb *init'
This runs the image in QEMU and attaches a GDB session, setting a breakpoint at the init() function in the Kernel.

​
Self-Test Mode

Run the built image in self-test mode: 
Meta/serenity.sh test
This passes system_mode=self-test to the Kernel.

​
Advanced Configuration

​
Custom QEMU Arguments

Set additional QEMU arguments: 
export SERENITY_EXTRA_QEMU_ARGS="-device virtio-serial"
Meta/serenity.sh run

​
Disk Image Types

Build different disk image formats: 
cd Build/x86_64
ninja limine-image      # Builds limine_disk_image with Limine
ninja grub-image        # Builds grub_disk_image with GRUB (BIOS)
ninja grub-uefi-image   # Builds grub_uefi_disk_image with GRUB (UEFI)
ninja extlinux-image    # Builds extlinux_disk_image with extlinux

​
Troubleshooting

​
Toolchain Outdated

If prompted to rebuild the toolchain after updates: 
rm Build/*/CMakeCache.txt

​
Filesystem Errors

If you see fusermount: failed to open /etc/mtab: 
ln -sv /proc/self/mounts /etc/mtab

​
Performance on Windows

If using native Windows QEMU with WSL2, QEMU accesses the ext4 partition via 9P network share, which may be slower. Your WSL2 distro is accessible at \\wsl$\{distro-name}.
Consider copying Build/_disk_image and Build/Kernel/Kernel to a native Windows partition before running.

Build docs developers (and LLMs) love

Get started for freeTalk to us