# SerenityOS - The dream of the '90s is alive! ## What is SerenityOS? SerenityOS is a new operating system written from scratch by Andreas Kling and many, many more open-source contributors. It is described as "a love letter to '90s user interfaces with a custom Unix-like core." ![](https://cdn-learn.adafruit.com/assets/assets/000/110/899/medium800/hacks_00-SerenityOS.jpg?1650311990) Why the 90s? Probably just feeling nostalgic, but it was an exciting time! It was the era of Windows 95, Mac System 7, and this new thing called Linux. GUIs had been around for a while but they were improving quickly. It sounds quaint now but we were excited about having more than 16 colors on the screen at once. It was amazing to be able to play a video on your computer. The average web page now probably has more multimedia playing than a typical 1990s computer could handle. The internet was becoming more widely available but unless you were lucky you had to use dial-up to connect. If you want the true 90s experience you should download this at 28.8 kbps and install it from floppy disks. Fortunately for us, SerenityOS only looks like the 90s, it's a fully modern system underneath! Let's build it and take a look. # SerenityOS - The dream of the '90s is alive! ## Build (Windows) In order to run SerenityOS under Windows, you'll need to use the Windows Subsystem for Linux (WSL) version 2, so you need Windows 10 (v2004 or higher) or Windows 11. WSL lets you run Linux binaries in Windows, so you can have a full Linux distribution available without needing a virtual machine or another computer. To install it you need an administrator command prompt - you can get to one by going to start, typing **cmd** , then selecting **Run as administrator** in the options for Command Prompt. ![](https://cdn-learn.adafruit.com/assets/assets/000/110/900/medium800/hacks_01a-cmd.jpg?1650312906) Now type `wsl --install` to start the install process. The default distribution is Ubuntu, but you can change it if you like. Check the list of available distributions with `wsl --list --online` and then install the one you want with `wsl --install -d `. It can take a while to install - at some point it will tell you to reboot and then finish up, prompting you to create a user account. ![](https://cdn-learn.adafruit.com/assets/assets/000/110/901/medium800/hacks_01-wsl-install.jpg?1650313425) Now that you have WSL2, you can start a terminal with the new Ubuntu (or other distro) shortcut in the start menu. Time to build! First you'll need QEMU for Windows, you can get it at: [https://www.qemu.org/download/#windows](https://www.qemu.org/download/#windows). Follow the link for the 64-bit installer and get the **qemu-w64-setup-YYYYMMDD.exe** file. Install at least the Tools and x86\_64 System emulation. Back in WSL2 land we can install the prerequisites to build SerenityOS. `sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo` Next we need GCC 11. The default Ubuntu install in WSL2 doesn't have it, so we can add it using these steps: `sudo add-apt-repository ppa:ubuntu-toolchain-r/testsudo apt updatesudo apt install gcc-11 g++-11` SerenityOS uses QEMU version 5 and will build it on its own but it needs a few libraries: `sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libspice-server-dev` All set! Now we can grab the SerenityOS repository. `git clone https://github.com/SerenityOS/serenity.git` `cd serenity` And now build QEMU: `Toolchain/BuildQemu.sh` ![](https://cdn-learn.adafruit.com/assets/assets/000/111/008/medium800/hacks_02-build.jpg?1650900775) Next build the toolchain: `Meta/serenity.sh rebuild-toolchain` And finally SerenityOS itself! `Meta/serenity.sh run` # SerenityOS - The dream of the '90s is alive! ## Build (macOS, Linux) On macOS you'll need [Homebrew](https://brew.sh/) and Xcode installed (get it in the App Store), plus you need to run Xcode once to let it install more tools. First you need to tell the system to use Xcode's tools: `sudo xcode-select --switch /Applications/Xcode.app` Now install the prerequisites: `brew install coreutils e2fsprogs qemu bash gcc@11 imagemagick ninja cmake ccache rsync zstd libvirt` If you have an Apple Silicon Mac make sure that you only have these tools in one brew environment, arm or x86. Using the native arm tools is going to be faster. There are two options for handling Serenity's ext2 filesystem, we'll use the simpler way with genext2fs. You can also use macFUSE, but it's a bit more complicated, check out the [build instructions](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructionsMacOS.md) to do that. `brew install genext2fs` That's it for prereqs! Now we can start building. Grab the SerenityOS repository: `git clone https://github.com/SerenityOS/serenity.git` `cd serenity` First build the toolchain: `Meta/serenity.sh rebuild-toolchain` Now the final step: `Meta/serenity.sh run` ![](https://cdn-learn.adafruit.com/assets/assets/000/111/032/medium800/hacks_03a-macserenity.jpg?1650906611) If you're running Linux, you can just install a few libraries and then start building, check out the [build instructions](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructions.md) for your specific distribution if it's not here. **Ubuntu / Debian** `sudo apt install build-essential cmake curl libmpfr-dev libmpc-dev libgmp-dev e2fsprogs ninja-build qemu-system-gui qemu-system-x86 qemu-utils ccache rsync unzip texinfo` You may need to install GCC 11 as well: `sudo add-apt-repository ppa:ubuntu-toolchain-r/testsudo apt updatesudo apt install gcc-11 g++-11` And some prerequisites for QEMU: `sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libspice-server-dev` **Arch** `sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu qemu-arch-extra ccache rsync unzip` Now it's the same as above to build the toolchain and run the OS: `git clone https://github.com/SerenityOS/serenity.git` `cd serenity` Depending on the distribution you may need to build qemu: `Toolchain/BuildQemu.sh` Then finish up: `Meta/serenity.sh rebuild-toolchain` `Meta/serenity.sh run` # SerenityOS - The dream of the '90s is alive! ## Running We did it, we built the OS! Now what do we do? Check it out! It's a full-featured system with a web browser, games, productivity apps, everything. Explore and see what you can find. ![](https://cdn-learn.adafruit.com/assets/assets/000/111/094/medium800/hacks_05-solitairewin.jpg?1650915874 Solitaire) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/096/medium800/hacks_06-mandelbrot.jpg?1650915963 Mandelbrot viewer) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/097/medium800/hacks_07-web.jpg?1650916008 Web browser) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/098/medium800/hacks_08-3dviewer.jpg?1650916019 3D file viewer) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/099/medium800/hacks_09-piano.jpg?1650916030 Piano) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/100/medium800/hacks_10-tips.jpg?1650916054 Tips on using SerenityOS) Check out the themes too! You can change the look of the whole system with a click. ![](https://cdn-learn.adafruit.com/assets/assets/000/111/166/medium800/hacks_10a-themes.jpg?1651080314) Keep in mind it's still in development, so things may not work perfectly. If you'd like to help make it better, you can! SerenityOS is open source and actively developed. If you want to update to the latest code, you can do: `git pull` `Meta/serenity.sh run`   # SerenityOS - The dream of the '90s is alive! ## More Info / Contributing You got it running and checked everything out, now what? You could get things running in a [VirtualBox VM](https://github.com/SerenityOS/serenity/blob/master/Documentation/VirtualBox.md), or even try it on [real hardware](https://github.com/SerenityOS/serenity/blob/master/Documentation/HardwareCompatibility.md). Check out the GitHub page for more! [[https://github.com/SerenityOS/serenity](https://github.com/SerenityOS/serenity)] SerenityOS is written in C++, so if you're familiar with it you can contribute code. Make sure you read [CONTRIBUTING.md](https://github.com/SerenityOS/serenity/blob/master/CONTRIBUTING.md) first and follow the policies there. You don't have to be a programmer, you can also contribute art! [[https://github.com/SerenityOS/artwork](https://github.com/SerenityOS/artwork)] Check out the [Discord](https://discord.gg/serenityos) and chat with the community! You can even watch the developers on YouTube: [Andreas](https://youtube.com/andreaskling), [Linus](https://youtube.com/linusgroh) Or just enjoy it :) ![](https://cdn-learn.adafruit.com/assets/assets/000/111/140/medium800/hacks_11-enjoy.jpg?1650999179) ## Related Guides - [NeoPIO: Drive lots of LEDs with Raspberry Pi Pico](https://learn.adafruit.com/neopio-drive-lots-of-leds-with-raspberry-pi-pico.md) - [How To Homebrew Game Boy Games](https://learn.adafruit.com/homebrew-game-boy-games.md) - [LEGO Set Lighting](https://learn.adafruit.com/lego-set-lighting.md) - [Electro-knit](https://learn.adafruit.com/electroknit.md) - [3D Scans for Low Poly Statues](https://learn.adafruit.com/low-poly-3d-scans-for-3d-printing.md) - [Pico Four Keypad](https://learn.adafruit.com/pico-four-key-macropad.md) - [Creating Custom Symbol Fonts for Adafruit GFX Library](https://learn.adafruit.com/creating-custom-symbol-font-for-adafruit-gfx-library.md) - [USB C CC Resistor Fixer Case](https://learn.adafruit.com/resistor-fixer-case.md) - [DIY Welded Bike Stand](https://learn.adafruit.com/diy-welded-bike-stand.md) - [Ikea Vindriktning Hack with QT Py ESP32-S3 and Adafruit IO](https://learn.adafruit.com/ikea-vindriktning-hack-with-qt-py-esp32-s3-and-adafruit-io.md) - [Alternative languages for programming the SAMD51 boards](https://learn.adafruit.com/alternative-languages-for-programming-samd-boards.md) - [Getting Started with Braille Output for CircuitPython REPL](https://learn.adafruit.com/getting-started-braille-output-circuitpython-repl.md) - [Spruce Up a Costume with MONSTER M4SK Eyes and Voice](https://learn.adafruit.com/spruce-up-a-costume-with-monster-m4sk-eyes-and-voice.md) - [Gravatars: What they are and how to add or change one](https://learn.adafruit.com/gravatars-what-they-are-and-how-to-add-or-change-one.md) - [EYE SHOOTOUT: Contrasting Open Source and Big Retail Electronics](https://learn.adafruit.com/eye-shootout-contrasting-open-source-and-big-retail-electronics.md)