Hobby kernel + userspace, built mostly from scratch. Composited GUI, dynamically linked ELF binaries, networking, Python applications, and more. https://toaruos.org/

K. Lange d051aa45ee file-browser: Use object icon for kernel modules 3 weeks ago
.github 186d44349a github: checkout the right commit of kuroko 4 months ago
apps d051aa45ee file-browser: Use object icon for kernel modules 3 weeks ago
base 14ae8e37d8 login-loop: Use a simple, 'modern' /etc/issue 3 weeks ago
boot 9037902717 boot: Rewrite README 1 month ago
build b35f7ac8c9 misaka: initial merge 4 months ago
kernel 0caa949550 ptrace: Inform non-parent tracer when tracee exits 3 weeks ago
kuroko @ 7e96bdeec1 20f79b9a86 kuroko: sync to fix string comparison crash 1 month ago
lib 4901a7e538 compositor: Add I-beam cursor; logic in terminal, file-browser 1 month ago
libc 59e0c80b3c ld.so: Expose some internal data for use by debugger 3 weeks ago
linker 59e0c80b3c ld.so: Expose some internal data for use by debugger 3 weeks ago
modules 60b3446f00 e1000: add ref link 1 month ago
util c04800d100 util: Add working bochsrc 1 month ago
.gitignore 5cdec2a98f kuroko: add managed modules to filesystem 2 months ago
.gitmodules 08a1b3d0a9 misaka: final merge prep 4 months ago
AUTHORS 420bd44c95 add AUTHORS 3 years ago
LICENSE 08a1b3d0a9 misaka: final merge prep 4 months ago
Makefile 1a44f8a2f3 boot: merge retooled EFI loader 1 month ago
README.md 44651da833 v1.99.6 1 month ago



ToaruOS is a "complete" operating system for x86-64 PCs with plans for ports to other platforms.

While many independent, hobby, and research OSes aim to experiment with new designs, ToaruOS is intended as an educational resource, providing a representative microcosm of functionality found in major desktop operating systems.

The OS includes a kernel, bootloader, dynamic shared object linker, C standard library, its own composited windowing system, a dynamic bytecode-compiled programming language, advanced code editor, and dozens of other utilities and example applications.

There are no external runtime dependencies and all required source code, totalling roughly 80,000 lines of (primarily) C, is included in this repository, save for Kuroko, which lives separately.

Screenshot Demonstration of ToaruOS's UI and some applications.


ToaruOS has been in development for over ten years, and the goals of the project have changed through out its life time.

When it was initiated in December 2010, the OS was a personal project, and its focus was on the individual learning of its author.

With time, ToaruOS's relatively advanced graphical interface and other features have inspired new hobby OSes, and the goals of the project shifted towards providing a reliable learning resource.

From its initial release through the middle of 2018, ToaruOS's userspace was built on top of the Newlib C standard library implementation as well as various third-party libraries such as Cairo and Freetype.

Since the release of 1.6.x, all third-pary runtime dependencies have been removed or replaced, and ToaruOS has been entirely "in-house".

In April 2021, work began on ToaruOS 2.0, which brings a rewritten kernel for x86-64 (and potentially other architectures) and support for SMP. The new "Misaka" kernel was merged upstream at the end of May.


  • Dynamically linked userspace with support for runtime dlopening of additional libraries.
  • Composited graphical UI with software acceleration and a late-2000s design inspiration.
  • VM integration for absolute mouse and automatic display sizing in VirtualBox and VMware Workstation.
  • Unix-like terminal interface including a feature-rich terminal emulator and several familiar utilities.
  • Optional third-party ports including GCC 10.3, Binutils, SDL1.2, Quake, and more.

Notable Components

  • Misaka (kernel), kernel/, a hybrid modular kernel, and the core of the operating system.
  • Yutani (window compositor), apps/compositor.c, manages window buffers, layout, and input routing.
  • Bim (text editor), apps/bim.c, is a vim-inspired editor with syntax highlighting.
  • Terminal, apps/terminal.c, xterm-esque terminal emulator with 256 and 24-bit color support.
  • ld.so (dynamic linker/loader), linker/linker.c, loads dynamically-linked ELF binaries.
  • Esh (shell), apps/sh.c, supports pipes, redirections, variables, and more.
  • Kuroko (interpreter), kuroko/, a dynamic bytecode-compiled programming language.

Current Goals

The following projects are currently in progress:

  • Rewrite the network stack for greater throughput, stability, and server support.
  • Improve SMP performance with better scheduling and smarter userspace synchronization functions.
  • Support more hardware with new device drivers for AHCI, USB, virtio devices, etc.
  • Bring back ports from ToaruOS "Legacy", like muPDF and Mesa.
  • Improve POSIX coverage especially in regards to signals, synchronization primitives, as well as by providing more common utilities.
  • Continue to improve the C library which remains quite incomplete compared to Newlib and is a major source of issues with bringing back old ports.
  • Replace third-party development tools to get the OS to a state where it is self-hosting with just the addition of a C compiler.
  • Implement a C compiler toolchain in toarucc.

Building / Installation

Building With Docker

General users hoping to build ToaruOS from source are recommended to use our prebuilt Docker image, which contains all the necessary tools:

git clone --recursive https://github.com/klange/toaruos
cd toaruos
docker pull toaruos/build-tools:1.99.x
docker run -v `pwd`:/root/misaka -w /root/misaka -e LANG=C.UTF-8 -t toaruos/build-tools:1.99.x util/build-in-docker.sh

After building like this, you can run the various utility targets (make run, etc.). Try make shell to run a ToaruOS shell using a serial port with QEMU.

Build Process Internals

The Makefile uses a Kuroko tool, auto-dep.krk, to generate additional Makefiles for the userspace applications and libraries, automatically resolving dependencies based on #include directives.

In an indeterminate order, the C library, kernel, userspace librares and applications are built, combined into a compressed archive for use as a ramdisk, and then packaged into an ISO9660 filesystem image.

Project Layout

  • apps - Userspace applications, all first-party.
  • base - Ramdisk root filesystem staging directory. Includes C headers in base/usr/include, as well as graphical resources for the compositor and window decorator.
  • boot - BIOS and EFI loader with interactive menus.
  • build - Auxiliary build scripts for future platform ports.
  • kernel - The Misaka kernel.
  • kuroko - Submodule checkout of the Kuroko interpreter.
  • lib - Userspace libraries.
  • libc - C standard library implementation.
  • linker - Userspace dynamic linker/loader, implements shared library support.
  • modules - Where loadable module sources will go when they are re-implemented for Misaka.
  • util - Utility scripts, staging directory for the toolchain (binutils/gcc).
  • .make - Generated Makefiles.

Running ToaruOS


qemu-system-x86_64 -M q35 -enable-kvm -m 1G -soundhw ac97 -cdrom image.iso


The legacy BIOS loader has been tested in VirtualBox and VMWare. For both, set up a virtual machine with an "Other (64-bit)" guest OS and attach the CD image. A least 32MB of display memory and 1GB of RAM are recommended. Some hardware configurations may not be supported.

EFI systems are also supported, though the EFI loader remains experimental. ToaruOS can also be booted in Multiboot-compatible loaders, such as GRUB.



ToaruOS is regularly mirrored to multiple Git hosting sites.


#toaruos on Libera (irc.libera.chat)


Is ToaruOS self-hosting?

Currently, in the development of ToaruOS 2.0, self-hosting builds have not been tested and some utilities may be missing.

Previously, with a capable compiler toolchain, ToaruOS 1.x was able to build its own kernel, userspace, libraries, and bootloader, and turn these into a working ISO CD image.

ToaruOS is not currently capable of building most of its ports, due to a lack of a proper POSIX shell and Make implementation. These are eventual goals of the project.

Is ToaruOS a Linux distribution?

ToaruOS is a completely independent project, and all code in this repository - which is the entire codebase of the operating system, including its kernel, bootloaders, libraries, and applications - is original, written by the ToaruOS developers over the course of eight years. The complete source history, going back to when ToaruOS was nothing more than a baremetal "hello world" can be tracked through this git repository.

ToaruOS has taken inspiration from Linux in its choice of binary formats, filesystems, and its approach to kernel modules, but is not derived in any way from Linux code. ToaruOS's userspace is also influenced by the GNU utilities, but does not incorporate any GNU code.