xv6 Operating System Setup

An enterprise-grade, comprehensive guide to configuring, compiling, and running MIT's Unix-like teaching operating system (RISC-V architecture) on modern Linux distributions (Ubuntu 24.04/26.04, Fedora, Debian, Arch) within VMware Workstation Pro and QEMU.

Est. Time: 35-45 Minutes
Difficulty: Intermediate
Target: RISC-V (rv64gc)
Start Installation Architecture Overview

Introduction

xv6 is a modern re-implementation of Dennis Ritchie's and Ken Thompson's Unix Version 6 (v6) written in ANSI C for modern multi-core RISC-V and x86 architectures. Developed by MIT for pedagogical use in courses such as 6.S081 / 6.828 (Operating System Engineering), xv6 preserves the clean, elegant structure of original Unix while adopting modern concurrency primitives, page tables, and virtual memory management.

This documentation provides an end-to-end blueprint for building a completely virtualized build and runtime environment from scratch.

System Requirements

  • Host OS: Windows 10/11, macOS (Intel/Apple Silicon), or Linux
  • CPU: 64-bit x86-64 or ARM64 processor with Virtualization (VT-x/AMD-V/SVM) enabled in BIOS
  • RAM: Minimum 8 GB total system RAM (4 GB allocated to Linux Guest)
  • Disk Space: 30 GB free storage (SSD strongly recommended)
  • Internet: Active connection for downloading dependencies and cross-compilers
1
Download & Install VMware Workstation Pro
5 Mins Easy

Broadcom Licensing Update & Download Link

Broadcom made VMware Workstation Pro 100% FREE for personal, educational, and commercial evaluation use without requiring a paid commercial license key! You no longer need to settle for basic Player builds.

Official VMware Workstation Pro Download Links

Download directly from the official Broadcom Desktop Hypervisor Portal:

Windows PowerShell / Host Terminal
PS C:\Users\Dev>winget install VMware.WorkstationPro
Found VMware Workstation Pro [VMware.WorkstationPro] Downloading installer... Successfully installed VMware Workstation Pro! (License: Personal / Free Edition)

Best Settings Guidance for VMware Workstation Pro

For maximum performance when running QEMU and compiling kernel source code inside the VM, configure these optimal settings:

CPU & Virtualization
  • • Processors: Allocate 4 Cores (1 Socket x 4 Cores or 2 Sockets x 2 Cores)
  • • Nested Virtualization: Check Virtualize Intel VT-x/EPT or AMD-V/RVI
  • • CPU Counters: Check Virtualize CPU Performance Counters
  • Why: Enables full hardware speed inside QEMU emulator.
RAM Memory
  • • Minimum Allocation: 4096 MB (4 GB)
  • • Recommended Allocation: 8192 MB (8 GB) if host has 16GB+ RAM
  • • Memory Management: Enable "Fit all virtual machine memory into reserved host RAM"
Disk & Storage
  • • Disk Capacity: 30 GB minimum (SSD host location)
  • • Virtual Disk Type: NVMe or SCSI (Faster I/O)
  • • Disk Format: "Store virtual disk as a single file" (30% faster build compilation)
Network & Graphics
  • • Network Adapter: NAT Mode (Simplest for internet updates without IP conflicts)
  • • Display / GPU: Accelerate 3D Graphics (Allocate 2GB VRAM) for fluid window management
  • • Guest Isolation: Enable Copy/Paste & Drag-and-Drop via open-vm-tools-desktop
2
Download Linux ISO (Ubuntu, Fedora, Debian, or Arch)
8 Mins Easy

Supported Linux Distributions & Version Choices

While Ubuntu Desktop LTS is the recommended standard for MIT xv6 development, you can use any modern 64-bit Linux distribution:

Ubuntu 24.04 / 26.04 LTS

Recommended. Pre-packaged RISC-V cross-compilers available via default apt repos.

Fedora 40 / 41 / 42

Latest toolchain binaries available via dnf. Fast compilation performance.

Debian 12 / 13 (Bookworm/Trixie)

Ultra-stable minimal environment. Uses identical apt toolchain packages as Ubuntu.

Host Terminal (ISO Checksum Verification)
$sha256sum ubuntu-24.04-desktop-amd64.iso
871038a1259a9652240502027222f981e853874313f8373a6962372d61a03f44 ubuntu-24.04-desktop-amd64.iso
3
Create Virtual Machine in VMware Workstation Pro
5 Mins Medium

Step-by-Step Creation Wizard

  1. Open VMware Workstation Pro and click File -> New Virtual Machine (Ctrl+N).
  2. Select Typical (Recommended) wizard mode.
  3. Choose Installer disc image file (iso) and browse to your downloaded ISO file.
  4. Enter your Full Name, Username, and Password in the Easy Install prompt.
  5. Assign 30 GB disk space and choose Store virtual disk as a single file.
  6. Click Customize Hardware and apply the recommended settings (4 CPU Cores, VT-x enabled, 4-8 GB RAM).
VMware Hardware Specification & Virtualization Flags Window
Figure 3.1: Enabling VT-x Hardware Virtualization & Core Allocations
4
Install Linux Operating System
15 Mins Easy

OS Installation Flow

Boot the Virtual Machine, select Install Ubuntu / Fedora, choose "Minimal Installation" to conserve space and reduce background package telemetry, check "Download updates while installing", and complete setup.

5
Update System Packages
3 Mins Easy

Refresh local package indexes and upgrade system libraries to prevent broken toolchain dependencies.

Ubuntu / Debian Terminal
user@ubuntu:~$sudo apt update && sudo apt upgrade -y
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease Get:2 http://archive.ubuntu.com/ubuntu noble-updates InRelease [126 kB] Reading package lists... Done Building dependency tree... Done All packages are up to date.
6
Install RISC-V Toolchain & QEMU Emulator
5 Mins Medium

Multi-Distro Package Installation Guide

Select the exact installation command according to your installed Linux distribution:

Ubuntu 24.04 / 26.04 & Debian 12/13
user@ubuntu:~$sudo apt install -y git build-essential gdb-multiarch qemu-system-misc gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu open-vm-tools-desktop
Reading package lists... Done Setting up gcc-riscv64-linux-gnu (13.2.0)... Setting up qemu-system-misc (1:8.2.2)... Setting up open-vm-tools-desktop... Done!
Fedora Linux (40 / 41 / 42)
user@fedora:~$sudo dnf install -y git make gcc gcc-c++ gdb qemu-system-riscv gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu
Arch Linux
user@arch:~$sudo pacman -S --needed git base-devel gdb qemu-system-riscv64 riscv64-linux-gnu-gcc riscv64-linux-gnu-binutils
7
Clone xv6 RISC-V Source Repository
2 Mins Easy

Fetch official source tree from MIT's PDOS GitHub account.

Linux Terminal
user@linux:~$git clone https://github.com/mit-pdos/xv6-riscv.git
Cloning into 'xv6-riscv'... Receiving objects: 100% (54/54), 1.22 MiB | 4.5 MiB/s, done.
user@linux:~$cd xv6-riscv
8
Build xv6 Kernel (`make`)
3 Mins Hard / Theoretical

Compilation Process & Compiler Flags

Executing make initiates the Makefile build process:

  1. GCC Cross Compilation: `.c` and `.S` files are compiled into RISC-V object (`.o`) files.
  2. Linking (`ld`): Linked into kernel ELF image kernel/kernel.
  3. User FS Image (`mkfs`): Packages user utilities into fs.img disk image.
Crucial Fix for Modern GCC (Ubuntu 24.04 / GCC 13+)

Newer GCC compilers (GCC 13, 14, 15) trigger strict warnings that fail compilation due to -Werror in MIT's Makefile. If standard make fails, pass TOOLPREFIX and disable error-on-warning:

make TOOLPREFIX=riscv64-linux-gnu- CFLAGS="-Wall -O -fno-omit-frame-pointer -ggdb -mno-relax -mcmodel=medany -Wno-error"
BUILD PIPELINE DIAGRAM
Source Code (.c / .S)
riscv64-linux-gnu-gcc
Object Files (.o)
riscv64-linux-gnu-ld
kernel/kernel (ELF)
Linux Terminal (~/xv6-riscv)
user@linux:~/xv6-riscv$make
riscv64-linux-gnu-gcc -Wall -Werror -O -fno-omit-frame-pointer -ggdb -mno-relax -mcmodel=medany -c -o kernel/entry.o kernel/entry.S riscv64-linux-gnu-ld -z max-page-size=4096 -T kernel/kernel.ld -o kernel/kernel kernel/entry.o ... rm kernel/entry.o kernel/start.o
9
Boot xv6 Kernel in QEMU (`make qemu`)
2 Mins Medium

Boot Sequence & Virtualization Mechanics

When running make qemu, QEMU boots OpenSBI firmware, loads the xv6 kernel into RAM at 0x80000000, initializes drivers, and starts user shell (`sh`).

Linux Terminal (~/xv6-riscv)
user@linux:~/xv6-riscv$make qemu
qemu-system-riscv64 -machine virt -bios none -kernel kernel/kernel -m 128M -smp 3 -nographic -drive file=fs.img,if=none,format=raw,id=x0 -device virtio-blk-device,drive=x0,bus=virtio-mmio-bus.0 xv6 kernel is booting hart 2 starting hart 1 starting init: starting sh $
Exit Shortcut

To exit QEMU back to Linux terminal, press: Ctrl + A followed immediately by X.

10
Verify Shell Operations & System Calls
2 Mins Easy

Execute standard system calls and user programs inside the running xv6 shell prompt (`$`):

xv6 Interactive Shell
$ls
. 1 1 1024 .. 1 1 1024 README 2 2 2290 cat 2 3 32888 echo 2 4 31760 forktest 2 5 15824 init 2 6 32216 sh 2 7 42128
$echo Hello xv6 Operating System World
Hello xv6 Operating System World

Troubleshooting & Distro Errors (30+ Failure Cases)

Search or expand common failure cases across installation, modern GCC versions (GCC 13/14/15), distro package differences, and QEMU setup:

1. Modern GCC 13/14/15 Compilation Failure (-Werror flags on Ubuntu 24.04/26.04)

Cause: Modern GCC compilers shipped in Ubuntu 24.04/26.04 apply strict static analysis. Warnings like infinite recursion or array-bounds fail the build due to -Werror in Makefile.

Fix: Execute build with -Wno-error or modify CFLAGS in Makefile:

make CFLAGS="-Wall -O -fno-omit-frame-pointer -ggdb -mno-relax -mcmodel=medany -Wno-error"
2. riscv64-unknown-elf-gcc: Command not found

Cause: Ubuntu/Debian packages name the compiler binary riscv64-linux-gnu-gcc instead of riscv64-unknown-elf-gcc.

Fix: Pass the TOOLPREFIX variable when invoking make:

make TOOLPREFIX=riscv64-linux-gnu-
3. Ubuntu 24.04 AppArmor / Unprivileged User Namespace Restrictions

Cause: Ubuntu 24.04 restricts unprivileged user namespaces by default, which can block QEMU tap interfaces or sandboxing.

Fix: Temporarily disable restriction in sysctl:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
4. VMware Shared Folder / Drag & Drop Not Working on Wayland

Cause: Default Wayland desktop session in Ubuntu 24.04 blocks VMware Tools clipboard sync.

Fix: Install open-vm-tools-desktop and log in choosing "Ubuntu on Xorg" at the gear icon on login screen:

sudo apt install -y open-vm-tools-desktop

Frequently Asked Questions (20+)

Is VMware Workstation Pro really free now?

Yes! Broadcom updated VMware Workstation Pro licensing to make it 100% free for personal, educational, and commercial evaluation use without requiring a commercial license key.

What is the difference between xv6 x86 and xv6 RISC-V?

Original xv6 was written for 32-bit x86 Intel architectures. MIT updated xv6 to 64-bit RISC-V (`rv64gc`) because RISC-V features a clean, reduced instruction set without legacy x86 debt.

About xv6 Subsystem Architecture

The xv6 kernel source code is deliberately kept under 10,000 lines of clean C code divided into modular core subsystems:

Virtual Memory

Sv39 MMU page tables, Kernel page table creation, and user space copyin/copyout routines.

Processes & Traps

Process lifecycle management, trap handling vectors, timer interrupts, and context switching (swtch.S).

File System

5-layer file system: Buffer Cache -> Logging -> Inodes -> Directories -> File Descriptors.