banan-os is a hobby operating system with a USB stack, a network stack and a package manager

A checklist that doubles as a roadmap

banan-os is described as the author's hobby operating system written in C++, currently supporting x86_64 and i686, with a live demo hosted on the author's site and a screenshot from QEMU running it. What makes the readme interesting is that the feature list is a checklist with tick boxes, and the unfinished boxes are as informative as the finished ones. The general section has ring 3 userspace, symmetric multiprocessing, a linear framebuffer through VESA and GOP, a network stack, a USB stack, audio support, ELF executable loading, a partial AML interpreter, a basic graphical environment with a terminal emulator, a status bar and a program launcher, ELF dynamic linking and copy-on-write memory. Only some nice apps remain unchecked in the graphical environment. The whole thing is BSD-2-Clause licensed and the mirror on GitHub exists because the upstream lives on the author's own git server.

The driver list shows where the effort went

The drivers section is a good snapshot of a hobby kernel's priorities. For storage there is NVMe and ATA covering IDE and SATA. For networking there are the E1000 and E1000E cards and the RTL8111, RTL8168, RTL8211 and RTL8411 family, which is a list that covers the emulated hardware most virtual machines and most cheap consumer adapters use. For audio there are AC97 and Intel HD Audio, and for input there is a PS2 keyboard and mouse. The USB section is the most detailed part of the checklist and the most honest, because it shows how much of the USB specification a hobby project tackles. xHCI is done, and so are keyboard, mouse, mass storage and hubs, while EHCI, OHCI and UHCI are still open, as is USB network and USB audio. And virtio devices, for network and storage, are entirely unchecked. That last box explains a lot about how the system is meant to be run, which is under QEMU with the hardware it does support.

The rest of the system, in lists

The network section has ARP, ICMP, IPv4, UDP, TCP and Unix domain sockets done, with SSL explicitly not done, which is the honest reason it is a hobby operating system rather than a real one. The filesystems section has a virtual filesystem, Ext2, FAT12, FAT16 and FAT32, and the Dev, Ram and Proc pseudo filesystems, with 9P still open. For booting, GRUB is supported and so is the custom BIOS bootloader, while a custom UEFI bootloader is not finished. The one that stands out is the partial AML interpreter, which is ACPI bytecode, and the reason it is partial is the usual one, that a machine will not boot far without at least enough of it to find the tables and hand over control. Put together, the picture is a system with a real userland and a real driver set, which is a considerable amount of work, and the checklist format makes the gaps impossible to miss.

One directory per component, headers included by absolute path

The code structure is described in two sentences and they are worth quoting because they say a lot about the build. Each major component and library has its own subdirectory, with the kernel, userspace and libc among them, and each directory contains a directory called include which has all of the header files of that component. Every header is included by its absolute path. That last convention is unusual and it is the kind of decision that only makes sense with a build system that mounts each component at a known root, and the repository layout shows the components as top level directories: bootloader/, kernel/, userspace/, toolchain/, ports/, script/, tools/, BAN/ and assets/, plus a CMakeLists.txt at the root, a .clangd for the language server, a .pre-commit-config.yaml and a .vscode directory. There is also a base-sysroot.tar.gz, which is the starting point for the sysroot the ports are built against.

The build starts by compiling a compiler

The build dependencies are listed for two package managers, with the apt line tested on Ubuntu 22.04 and the pacman line for Arch.

The apt list is tested on Ubuntu 22.04 and the pacman list covers Arch, and both include the compiler toolchain, ninja, the textinfo, bison and flex packages, the GMP, MPFR and MPC development libraries that GCC needs, parted, QEMU for x86 and the CPU checker.

Then there is the step that makes this project unusual. To build the toolchain for the operating system you run one command, and the note says the following step has to be done only once and that it might take a long time since binutils and GCC are being compiled.

./bos toolchain

So the project builds its own compiler and assembler rather than using the host toolchain, which is what a system aiming at a freestanding target eventually needs and what makes the rest of the build self-contained. The script is called bos, and the same script builds and runs the system afterwards.

./bos qemu
./bos qemu-nographic
./bos qemu-debug
./bos bochs

You can also build the kernel or the disk image without running them, which is the useful pair when you are working on the kernel and not on the userland.

./bos kernel
./bos image

Root access is needed for disk image creation and modification, which the readme says plainly.

Environment variables instead of configuration files

The build script is configured through environment variables, and the set of them covers the axes you would expect. To build for other architectures you set BANAN_ARCH, with i686 given as the example. To change the bootloader you set BANAN_BOOTLOADER, with the supported values being BANAN, the custom bootloader, and GRUB. To run with UEFI you set BANAN_UEFI_BOOT to 1, and you also have to set OVMF_PATH to the correct OVMF file, whose default is /usr/share/ovmf/x64/OVMF.fd. To build an image with no physical root filesystem but an initrd you set BANAN_INITRD to 1, which the readme says can be used when testing on hardware with an unsupported USB controller, and if BANAN_INITRD is set to a value larger than 1 the initrd is gzip compressed. If you have corrupted the disk image you can delete build/banan-os.img and the build system will create a new one, or run the image-full command. For real hardware there is a script that generates a compressed ISO at build/banan-os.iso, which can be copied straight to a USB drive with dd, and there is a zsh completion script that can be copied to /usr/share/zsh/site-functions/ or added to the fpath in .zshrc.

xbps for ports, and a contributor policy that asks first

banan-os uses xbps as its package manager for ports, with all upstream ports packaged into xbps packages hosted on a repository on the author's server. The sysroot's packages are managed through the bos wrapper, and you can also use xbps-install, xbps-remove and xbps-query directly with the repository and sysroot set to the right values, with the example given being the installation of xbps itself inside the operating system.

./bos xbps-install -S xbps

The contribution section is the most unusual part of the readme, and it is a policy rather than a process. Merging contributions is not as trivial as it would be on GitHub, because the upstream is hosted on the author's own server, and pull requests can still be sent on GitHub where the author says he should be able to download the diff and apply it manually, with an account on the git server offered on request. Then the request that matters, because the project is mostly a learning experience for the author, and contributors are asked to contact him about adding new features first, with the warning that a pull request about something he was planning to do himself, which was not discussed in advance, will probably be closed. Bug fixes are always welcome. The commit format is prescribed, with a subject line of the form Subject: Description, where the subject names the area touched such as Kernel, Shell or BuildSystem, and the body describing the change and the reasoning, and every commit should pass the pre-commit hook defined in .pre-commit-config.yaml.

Editorial conclusion

banan-os suits a reader who wants to see one person's operating system taken from a bootloader to a graphical shell in readable C++, and it suits anyone who wants a concrete example of what a small hobby kernel actually has to implement. It is the wrong tool for production use, and it is the wrong choice if you want a maintained system with drivers for modern hardware, since the virtio device support is still an open item and the USB controller coverage is partial. Before building it, read the note that the toolchain step has to be done only once and takes a long time, because binutils and GCC are compiled from source, and check whether you have root access, since creating and modifying the disk image needs it. The last push was on 2026-09-22 and the repository publishes no releases.

Frequently asked questions

Official sources

1. Bananymous/banan-os on GitHub
2. Issues
3. License: BSD-2-Clause
4. Project website
5. README