Skip to main content

​
Quick Start Guide

Get Redox OS up and running quickly on your system. This guide will walk you through building a Redox OS image using the recommended Podman build method.
New to Redox? This quick start focuses on getting you a working Redox image fast. For detailed installation and build options, see the Installation Guide.

​
What is Redox OS?

Redox is a Unix-like operating system written in Rust with a microkernel design. Key features include:

Memory Safe

Written entirely in Rust for memory safety

Microkernel

Fault isolation and improved security

POSIX Compatible

Run Linux and BSD programs

Modern Tooling

Comprehensive build system with Podman

​
Prerequisites

Before building Redox, ensure you have:
  • Linux, macOS, or BSD system (Windows via WSL2)
  • At least 8 GB RAM (16 GB recommended)
  • 30-60 GB free disk space
  • Reliable internet connection for downloading dependencies
  • Podman or Docker (Podman recommended)

​
Build Methods

Redox supports two build methods:

​
Quick Start: Podman Build

1

Install Podman

Install Podman on your system:
sudo apt install podman
2

Download and Run Bootstrap Script

Download the Podman bootstrap script and run it:
curl -sf https://gitlab.redox-os.org/redox-os/redox/raw/master/podman_bootstrap.sh -o podman_bootstrap.sh
time bash -e podman_bootstrap.sh
The bootstrap script will:
  • Clone the Redox repository
  • Build a Podman container with all dependencies
  • Set up the build environment
This takes 5-15 minutes depending on your internet connection.
3

Navigate to Redox Directory

cd redox
4

Build Redox

Build a complete Redox OS image:
make all
On systems without SELinux (like Ubuntu), use:
make all USE_SELINUX=0
The build process takes 30-90 minutes depending on your hardware. It will:
  • Download and compile all packages
  • Build the kernel and userspace
  • Create a bootable disk image
5

Run Redox in QEMU

Once the build completes, start Redox in QEMU:
make qemu
For KVM acceleration (much faster), use:
make qemu kvm=yes
You should see Redox boot and reach the Orbital desktop environment!

​
Build Configuration

You can customize your build with different configurations:
Full desktop environment with COSMIC apps:
make all CONFIG_NAME=x86_64/desktop

​
Architecture Support

Build for different CPU architectures: 
make all ARCH=x86_64

​
Common Make Targets

Here are the most useful make commands:
CommandDescription
make allBuild complete OS image
make liveBuild live ISO image
make qemuRun in QEMU emulator
make mountMount the filesystem for inspection
make cleanClean build artifacts
make rebuildClean and rebuild from scratch
See the complete Make Commands Reference for all available targets and options.

​
Next Steps

Explore the Architecture

Learn about Redox’s microkernel design

Build System Details

Understand the build system in depth

Start Contributing

Join the Redox development community

Hardware Compatibility

Check if your hardware is supported

​
Troubleshooting

On non-SELinux systems, make sure to use:
make all USE_SELINUX=0
Try using software rendering:
make qemu vga=no
  • Enable KVM if on Linux: make qemu kvm=yes
  • Use a native build instead of Podman for faster iteration
  • Ensure you have enough RAM (16 GB recommended)
Clean the container and rebuild:
make container_clean
bash podman_bootstrap.sh

​
Getting Help

Need Help?

Build docs developers (and LLMs) love

Get started for freeTalk to us