ToaruOS 1.0

@klange klange released this Jan 30, 2017 · 53 commits to master since this release

The latest version of ToaruOS is v1.0.4.

If you are building from source, it is recommended you build latest master.

ToaruOS 1.0

ToaruOS is a complete hobby operating system, including a kernel and userspace with many graphical applications. This is the first release considered to be "user-ready", but please keep in mind that ToaruOS is a hobby project and it may not be stable or suitable for any purpose you might have for an operating system. This release represents the culmination of many years of development, research, and learning.


This release has been six years in the making. The project started when I was still in university, studying computer science at the University of Illinois at Urbana-Champaign. Many of my classmates had decided to take ECE391 - a course offered by the department of Electrical and Computer Engineering which was primarily known for its final project: a basic multitasking operating system. I, however, was on track for an early graduation, and the course offered no credits for me, having already taken the CS department's "equivalent" (a systems engineering course, which I enjoyed immensely, but was definitely not about operating systems). Unable to take ECE391, I set off on my own to build an operating system that met its requirements.

ToaruOS has seen many contributions from other developers over its years. For a period of time while I was still in school, I had taken over management of UIUC's SIGOps student chapter with the goal of bringing in classmates to work on new features for the OS. From this came much of the underlying functionality of the GUI, including the shared memory subsystem. Other notable features contributed by others include much of the x86 assembly elements which were re-written in GAS from earlier YASM sources, the audio drivers and mixer, and much of the network stack.

As I returned to the software industry after my university years, ToaruOS became a weekend project. I went through many hiatuses over the past few years, and development has often been in spurts as something piques my interest. The months leading up to this release have been some of the most active for the OS, seeing the addition of a dynamic linker, upgrades to our GCC builds to 6.3 (which had been using 4.6, the version of GCC released in 2011 when the project was getting started), the growth of a Python userspace ecosystem, and much more.

Now, finally, it is time to tag "v1.0.0". Long ago, I had drafted a list of features I wanted to see in this release, and while many were considered ambitious, one by one, each box has been checked. But, of course, this is not the end, and I expect that I will make many more releases in this 1.x series, be they bug fixes or feature additions.

Features of the OS

ToaruOS's kernel in its current form is 32-bit, non-SMP, monolithic (but modular), and Unix-like. It supports processes, threads, shared memory, files, pipes, TTYs, packet-based IPC, and basic IPv4 networking. Driver modules allow for access to EXT2 and ISO9660 filesystems, PATA and ATAPI disk access for hard drives and CDs, framebuffer support on most virtual machines (as well as bootloader-assisted generic framebuffer support), networking on AMD PCnet FAST, Realtek RTL8139, and Intel PRO/1000-series NICs, PS/2 mice and keyboards, audio on Intel AC'97 chipsets, as well as special support for VirtualBox's guest additions.

The userspace includes a dynamic linker, a full-featured compositing windowing system, many Unix-like utilities, a port of Python 3.6 (including many binding libraries for the ToaruOS windowing environment), and several graphical applications (including a package manager).

Several third-party software packages have been ported to the OS, including Vim, GCC and Binutils, MuPDF, SDL, Quake, Bochs, and more, available through the package manager.

About the Name

Many people ask what "ToaruOS" means, where the name came from, and how to pronounce it. I will start by saying that the name is a reference to a series of light novels, manga, and anime, and that like the titles of those works, an acceptable translation of "ToaruOS" might be "A Certain OS". This name came about as a parody of the myriad generically-named hobby operating systems out there - many of them called things like "My OS". In the early days of development, ToaruOS was rather consistently referred to as とあるOS, and over time this changed to the romanized ToAruOS and later to ToaruOS simply because it was easier for people to read and write. The logo for the OS still bears the kana writing and is blatantly ripped from the logos of its namesakes. Following the Toaru theme, codenames for releases throughout development have come from characters from the series. As for how to pronounce it, here's a handy guide for English speakers: toe ah roo (oh ess).

Building ToaruOS

Building ToaruOS from scratch can be tricky. The recommended build environment for ToaruOS is Ubuntu 16.04 or newer. Clone the repository and run the following commands:

make toolchain               # This will take several minutes (possibly up to 30, or more)
. toolchain/      # Adds the toolchain binaries to $PATH
make                         # Builds the kernel, modules, and core userspace.
toolchain/  # Builds Python 3.6
toolchain/ # Builds PyCairo bindings to Cairo
make clean-disk; make        # Rebuilds the disk image with Python included.

You can run this development image with QEMU (make run) or VirtualBox (make virtualbox).

It is recommended that you also build a separate CD image. With your toolchain from the previous step activated, clone the repository again (to a different directory), and run:

make cdrom

This will produce a toaruos.iso. You can run this image with make run-cdrom or with any supported environment.

Running ToaruOS

While we do what we can to ensure compatibility with actual hardware, we focus our development efforts on running ToaruOS in virtual machines such as QEMU and VirtualBox. If you choose to run ToaruOS on "bare metal", we recommend using the live CD, which should also function as a bootable USB stick on some platforms. Please be aware of the hardware requirements of the OS, both when using ToaruOS with real hardware and when using virtual machines.

The preferred environments are as follows:

  • VirtualBox:
    • OS Type: Other/Unknown
    • Memory: At least 1024MB
    • Video Memory: May need to be adjusted if you have a large display
  • QEMU:
    • qemu-system-i386 -M accel=kvm:tcg -m 1G -vga std -net nic,model=rtl8139 -net user -soundhw ac97,pcspk -cdrom toaruos.iso

If you are trying to run ToaruOS in Bochs, please set your clock to sync to realtime and be aware that the compositing window manager is somewhat demanding, so performance on Bochs (and other software emulators) may not provide a desirable experience.

The default user on both the CD and development hard disks is local with password local. You may also make use of the root user, with password toor, but a sudo implementation is available if you need to perform privileged tasks as a regular user.

Netboot Image

Attached to this release is a 2MB CD ISO labeled "netboot.iso". This image can be used on platforms with supported network configurations to boot into a downloaded userspace obtained from our website or a mirror. It will not function in environments without network support.

Hardware Compatibility / Drivers


  • preset - 32-bit linear framebuffer set up by bootloader
  • qemu - Bochs/QEMU (and VirtualBox) virtual display device
  • vmware - VMware virtual display device

(The display driver will automatically detect from the above list by default, so you should not need to worry about setting this unless you are crafting your own Grub configuration.)


  • e1000 - Intel PRO/1000 MT Desktop
  • pcnet - AMD PCnet-FAST II/III
  • rtl - Realtek RTL 8139

(All of these drivers are available by default, and if a supported network card is detected the driver for it will be initialized automatically.)


  • ac97 - Intel ICH AC'97
  • pcspkr - Basic beeper support

We are working to support the Intel HD Audio chipset in the future.


  • ata - ATAPI and (P)ATA with DMA support
  • ataold - (P)ATA without DMA support

(If you are using ToaruOS on real hardware, you may need to try the ataold driver if you have issues with the ata driver, or disable the ATA drivers entirely if you are running from a live CD.)

File Systems

  • ext2 - Ext2 (basic write support is available, but may be unstable - detailed bug reports are appreciated)
  • iso9660 - Read support for CD filesystems


  • ps2kbd - PS/2 keyboard
  • ps2mouse - PS/2 mouse (with scrollwheel and middle click)
  • vboxguest - Provides support for the "Mouse Integration" feature of VirtualBox

Things to Try

Install Packages

If you are running ToaruOS in an environment where networking is supported (QEMU and VirtualBox as configured in the previous section), you may want to try installing packages through the Package Manager. You can use the package manager from the command line:

sudo get-py vim # for example, will install the text editor

... or through the graphical interface available from the "Packages" icon on the desktop. Package removal is not available at this time.

Read Documentation

ToaruOS comes with a documentation viewer called Help Browser which provides rich-text documentation from some of the installed software.

Explore the Terminal

ToaruOS provides a Unix-like environment with many command line utilities and a feature-rich terminal emulator. A relatively complete Python installation comes pre-installed on the live CDs. You can obtain additional applications, such as Vim or GCC, through the package manager.

Play Games

ToaruOS comes pre-installed with some games such as 2048 and "Mines".

With the package manager, you can download additional games such as id Software's Doom and Quake (shareware versions). These games will be added to the Applications menu under the "Games" submenu. A Super Nintendo emulator (snes9x) is also available, but you'll need to obtain your own ROMs to use it.


Contributing to ToaruOS

Please note that ToaruOS was started as a project for me to learn and build things on my own. As such, larger contributions are discouraged as I usually want to build things myself. However, smaller bug fixes, and independent software ports, are welcome.


You can join us on Freenode ( in #toaruos.


There is a long list of goals for ToaruOS 2.0, including a new 64-bit, SMP-capable kernel. Many other changes are expected in the interim, including improvements to existing applications and possibly new device drivers.