Skip to main content
While it is possible to run Serenity on physical x86-64-compatible hardware, it is not yet ready to be used by non-technical users who aren’t prepared to report bugs or assist with its development. There are currently no pre-built install images, so bare-metal installation requires building from source.

​
Hardware Requirements

​
Minimum Requirements

  • CPU: x86-64 compatible processor
  • RAM: 256 MB minimum
  • Storage: 2 GB or larger SATA, NVMe, or USB drive

​
Supported Hardware

​
Storage Controllers

  • SATA controllers
  • NVMe controllers
  • USB storage (xHCI and UHCI host controllers only)

​
Network Cards

  • Intel e1000 (tested with QEMU and VirtualBox; may work with 82545XX, 82540XX, 82546XX chipsets)
  • Intel e1000e
  • Realtek 8168

​
Sound Cards

  • Intel AC’97
  • Intel HDA PCI devices

​
Graphics

  • No real GPU support currently
  • Relies on multiboot or EFI GOP framebuffer
  • No OpenGL or Vulkan support
  • No accelerated video playback/encoding
  • No WiFi support
You must be willing to wipe your disk’s contents to write the Serenity image. Back up any important data first!

​
Creating a Serenity GRUB Disk Image

1

Build SerenityOS from source

Follow the build instructions to build the OS. Run up to and including:
Meta/serenity.sh image <arch>
2

Build the GRUB disk image

After the OS has built, create the bootable image:For UEFI systems:
cd Build/<arch>
ninja grub-uefi-image
For legacy BIOS systems:
cd Build/<arch>
ninja grub-image
This creates grub_uefi_disk_image or grub_disk_image with GRUB2 installed.
Building the GRUB image requires parted and grub2 (on Arch: grub) to be installed on your system.

​
Writing the Image to Physical Media

The following command will completely erase the target device. Double-check the device path before proceeding!

​
Using dd (Linux/Unix)

sudo dd if=grub_uefi_disk_image of=/dev/sdx bs=64M && sync
Replace /dev/sdx with your target device (e.g., /dev/sdb).
The bs=64M argument is optional but speeds up the data transfer.

​
Using WSL (Windows Subsystem for Linux)

You can find WSL files in Windows Explorer under: 
\\wsl$\<distro name>\<path to serenity directory>
Use any image flashing application like Rufus or balenaEtcher to write the image.

​
Boot Parameters

​
Root Partition

If using the BIOS disk image, you may need to adjust the root= boot parameter in the GRUB boot menu to refer to the correct partition. See the boot device addressing documentation for more details.

​
NVMe Drives

If you installed Serenity to an NVMe drive and it fails to initialize, try adding the nvme_poll boot parameter.

​
Console-Only Mode

To boot into console-only mode (useful if graphics initialization fails): 
graphics_subsystem_mode=limited
This forces the kernel to not initialize any framebuffer devices, and SystemServer will detect this condition and skip starting WindowServer.

​
Multiboot Support

Serenity uses the GRUB2 bootloader, so it should be possible to multiboot it with any other OS that can be booted from GRUB2 post-installation.

​
Troubleshooting Boot Issues

Many troubleshooting guides recommend using screen for serial console monitoring, but cu is easier for copying output.
1

Install cu

sudo apt install cu
2

Add user to dialout group

sudo usermod -aG dialout YourLinuxUserName
You must log out and log back in after running this command.
3

Connect to serial console

cu -s 57600 -l /dev/ttyUSB0

​
Without Serial Port

During the boot process, important kernel messages are printed to the screen. If the system hangs, the last message visible may indicate an assertion or kernel panic.

​
PC Speaker Debugging

If no output is visible, the Kernel may panic before video initialization. Try debugging the init sequence with the PC speaker to identify where it gets stuck.

​
Boot into Console Mode

Force console-only boot if graphics initialization is problematic: 
graphics_subsystem_mode=limited
This prevents framebuffer device initialization, and SystemServer will skip WindowServer startup.

​
Post-Installation

Once Serenity boots successfully on your hardware:
  1. Test all hardware components
  2. Report any issues on the SerenityOS GitHub
  3. Help improve hardware compatibility by contributing fixes
Serenity is under active development. Hardware support is continually improving, but not all features work on all systems yet.

Build docs developers (and LLMs) love

Get started for freeTalk to us