Skip to main content
There are currently known issues with running Serenity in VirtualBox. Please refer to the open issue for a list of currently known problems. At the time of writing, audio and networking do not work in VirtualBox.

​
Creating the Disk Image

Before creating a disk image for VirtualBox, you need to create a GRUB image as described in the bare metal installation guide.
Skip the final step of the bare metal guide (writing to physical drive) as that’s only relevant for real hardware.
You cannot use the same disk image created for QEMU. Using that image will halt immediately with the message FATAL: No bootable medium found! System halted.

​
Converting the Image

There are two ways to convert the GRUB disk image to VirtualBox format:

​
Using QEMU (if installed)

qemu-img convert -O vdi /path/to/grub_disk_image /path/to/output/serenityos.vdi

​
Using VirtualBox Only

VBoxManage convertfromraw --format VDI /path/to/grub_disk_image /path/to/output/serenityos.vdi

​
Set Disk Identifier

Set an identifier to prevent mismatches when updating the disk image: 
VBoxManage internalcommands sethduuid serenityos.vdi 19850209-0000-0000-0000-000000000000
On Windows, if QEMU or VirtualBox are not in your PATH, navigate to their installation folder and prefix commands with ./

​
Creating the Virtual Machine

These instructions were written with VirtualBox v6.1.12 in mind. Steps may vary slightly for other versions.
1

Open Create Virtual Machine dialog

Open the Create Virtual Machine dialog and switch to Expert Mode.
2

Configure basic settings

  • Give it any name and storage location
  • Set Type to Other
  • Set Version to Other/Unknown (64-bit)
3

Set memory size

Serenity requires at minimum 512 MiB of memory. The currently recommended size is 1 GiB (1024 MiB).
4

Add existing disk

For Hard disk:
  1. Select Use an existing virtual hard disk file
  2. Click the folder icon to open the Hard Disk Selector
  3. Click Add and browse to your converted VDI image
  4. Click Choose
5

Create the VM

Click Create to finalize the virtual machine.

​
Configuring the Virtual Machine

Serenity requires specific configuration changes to boot properly.

​
Required Settings

1

Enable PAE/NX

  1. Open Settings
  2. Go to System > Processor tab
  3. Tick Enable PAE/NX
2

Configure audio

  1. Go to Audio
  2. Set Audio Controller to SoundBlaster 16
Audio does not currently work in VirtualBox.

​
Verify Settings

Check these settings to ensure compatibility:

​
Storage Controller

  1. In Storage, click on the Controller
  2. Verify the controller type is AHCI (SATA) or NVMe
Any other controller type is guaranteed not to work, as Serenity does not currently support them.

​
Network Adapter

  1. Go to Network > Advanced dropdown
  2. Verify Adapter Type is NOT set to Intel PRO/1000 MT Desktop (82540EM)
While the Intel PRO/1000 MT Desktop (82540EM) is the only adapter type Serenity currently supports, it does not currently work in VirtualBox. Networking does not work at this time.

​
Troubleshooting

​
Blinking Cursor After GRUB Menu

If you only see a blinking cursor after selecting an option in the GRUB menu:
1

Check PAE/NX is enabled

Verify that you have enabled PAE/NX in Settings > System > Processor tab.
2

Verify 64-bit configuration (if using 64-bit)

If using a 64-bit disk image, check that Version is set to Other/Unknown (64-bit) instead of Other/Unknown in Settings > General.
For more boot issues, see the troubleshooting documentation.

​
Optional Configuration

​
Serial Debugging

To enable serial debugging:
1

Enable serial port

  1. Go to Serial Ports
  2. Enable port 1
2

Configure port mode

Set Port Mode to Raw File (recommended) or another mode if you know what you’re doing.
3

Set output path

Set Path/Address to where you want to store the serial output file. This must include the filename.

​
Video Memory for High Resolutions

The default 16 MB of video memory is sufficient for default resolution, but not for all supported resolutions:
  • Default resolution: 16 MB (default)
  • 2560x1080 resolution: Minimum 22 MB required
Adjust video memory in Settings > Display > Video Memory if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us