Skip to main content
Running Redox OS in a virtual machine is the easiest and safest way to try the operating system without affecting your existing setup. QEMU is the primary development and testing platform for Redox OS and provides the best compatibility and performance.
The Redox build system includes built-in QEMU support with optimized configurations for each architecture.

​
Quick Start

After building Redox, you can launch it in QEMU with: 
make qemu
This automatically configures QEMU with appropriate settings for your chosen architecture.

​
Architecture-Specific Configurations

Default Configuration:
  • Machine: Q35
  • CPU: Core 2 Duo (or host CPU with KVM)
  • Cores: 4
  • Memory: 2048 MB
  • Firmware: UEFI (OVMF)
  • Storage: NVMe
  • Network: Intel e1000
  • Graphics: Standard VGA
  • Audio: Intel HDA
Command:
make qemu

​
QEMU Customization Options

You can customize the QEMU configuration using make variables:
Enable KVM (Linux) or HVF (macOS):
make qemu kvm=yes
KVM/HVF is automatically enabled when the host and guest architectures match. Disable with kvm=no.
Change disk type:
make qemu disk=nvme    # NVMe (default for x86-64)
make qemu disk=ata     # AHCI/IDE
make qemu disk=virtio  # VirtIO block
make qemu disk=usb     # USB storage
Change GPU type:
make qemu gpu=vga          # Standard VGA (default)
make qemu gpu=virtio       # VirtIO GPU
make qemu gpu=virtio-gl    # VirtIO GPU with OpenGL
make qemu gpu=no           # Headless (serial only)
Network options:
make qemu net=no           # No network
make qemu net=redir        # User mode with port forwarding
make qemu net=rtl8139      # RTL8139 adapter
make qemu net=virtio       # VirtIO network
make qemu bridge=br0       # Bridged networking
Port forwarding (net=redir):
  • SSH: localhost:8022 → guest:22
  • HTTP: localhost:8080 → guest:80
  • Additional: 8081, 8082, 8083, 64126
Audio options:
make qemu audio=no         # No audio
make qemu audio=ac97       # AC'97 (i586 default)
# Intel HDA is default for x86-64
Adjust resources:
make qemu QEMU_SMP=8 QEMU_MEM=4096
GDB debugging:
make qemu gdb=yes         # Wait for GDB connection
make qemu gdb=nonblock    # Allow GDB attach without blocking
GDB will listen on port 1234.

​
Advanced QEMU Examples

# Maximum performance with KVM and VirtIO
make qemu kvm=yes disk=virtio net=virtio gpu=virtio

​
Serial Console

QEMU provides serial console access by default:
Serial output is multiplexed to stdio. Use Ctrl+A, C to access the QEMU monitor.
To log serial output to a file: 
make qemu qemu_serial_logfile=serial.log

​
QEMU Firmware Locations

The build system automatically detects firmware files: UEFI for x86-64:
  • /usr/share/ovmf/OVMF.fd
  • /usr/share/OVMF/OVMF_CODE.fd
  • /usr/share/qemu/edk2-x86_64-code.fd
UEFI for ARM64:
  • /usr/share/AAVMF/AAVMF_CODE.fd
  • /usr/share/qemu/edk2-aarch64-code.fd
UEFI for RISC-V:
  • /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd
  • /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd

​
VirtualBox

VirtualBox provides an alternative virtualization option with a graphical interface.
VirtualBox support is less mature than QEMU. Some features may not work correctly.

​
Quick Start

After building Redox, create and launch a VirtualBox VM: 
make virtualbox
This will:
  1. Delete any existing “Redox” VM
  2. Create a new VM with recommended settings
  3. Convert and attach the hard drive image
  4. Start the VM

​
VirtualBox Configuration

The automated setup configures:
SettingValue
Memory2048 MB
Video Memory32 MB
Storage ControllerIntel AHCI (SATA)
NetworkNAT with Intel PRO/1000 MT Desktop (82540EM)
AudioIntel HD Audio
USBDisabled (recommended for compatibility)
KeyboardPS/2
MousePS/2

​
Manual VirtualBox Setup

If you prefer to configure VirtualBox manually:
1

Create a new VM

  • Name: Redox
  • Type: Other
  • Version: Other/Unknown (64-bit)
2

Configure system settings

  • Base Memory: 2048 MB or more
  • Processors: 1 or more
  • Enable I/O APIC
3

Configure display

  • Video Memory: 32 MB
  • Graphics Controller: VBoxVGA or VMSVGA
4

Attach storage

  1. Create a SATA controller
  2. Convert the Redox image to VDI format: 
    VBoxManage convertfromraw build/x86_64/harddrive.img build/x86_64/harddrive.vdi
  3. Attach the VDI file to the SATA controller
5

Configure network

  • Adapter 1: Enabled
  • Attached to: NAT
  • Adapter Type: Intel PRO/1000 MT Desktop
  • Enable cable connected
6

Configure audio

  • Enable Audio
  • Audio Controller: Intel HD Audio
7

Disable USB

USB support should be disabled for better compatibility with Redox.

​
VirtualBox Network Capture

The automated setup enables network packet capture: 
cat build/x86_64/network.pcap | wireshark -k -i -

​
VirtualBox Serial Log

Serial output is logged to: 
build/x86_64/serial.log

​
Comparison: QEMU vs VirtualBox

FeatureQEMUVirtualBox
PerformanceExcellent with KVM/HVFGood
CompatibilityBestGood
SetupAutomated via MakefileAutomated via Makefile
GUIOptional (GTK/SDL)Native GUI
DebuggingBuilt-in GDB supportLimited
Multi-archx86, ARM, RISC-Vx86 only
Recommended ForDevelopment, testingDesktop evaluation

​
Live ISO vs Hard Drive Image

Redox can boot from either format:
Build and run:
make live=yes qemu
Advantages:
  • No installation required
  • Boot from CD-ROM
  • Safe for testing
Disadvantages:
  • Read-only system
  • No persistence
  • Slower boot

​
Troubleshooting

Check firmware installation:
ls /usr/share/ovmf/OVMF.fd
ls /usr/share/qemu/edk2-*.fd
Install the appropriate UEFI firmware package for your distribution:
  • Ubuntu/Debian: ovmf qemu-efi-aarch64 qemu-efi-arm
  • Fedora: edk2-ovmf edk2-aarch64
  • Arch: edk2-ovmf edk2-armvirt
Try different GPU options:
make qemu gpu=virtio
make qemu gpu=no serial=yes
Check network configuration:
make qemu net=redir  # Use port forwarding
make qemu net=no     # Disable network
Enable hardware acceleration:
make qemu kvm=yes              # Linux
# Or for macOS, HVF is auto-detected
And use VirtIO devices:
make qemu kvm=yes disk=virtio net=virtio
  • Ensure USB is disabled
  • Try switching graphics controller
  • Check that the VDI conversion succeeded
  • Verify SATA controller is set to AHCI

​
Next Steps

Running on Real Hardware

Ready to install Redox on physical hardware

Building Redox

Learn how to build Redox from source

Build docs developers (and LLMs) love

Get started for freeTalk to us