> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/serenityOS/serenity/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Build and run SerenityOS on your machine using QEMU with this step-by-step guide

<Note>
  The first build will take some time as it downloads database files and builds the cross-compiler toolchain. Subsequent builds will be much faster.
</Note>

## Prerequisites

SerenityOS supports building on Linux, macOS, Windows (with WSL2), and many other \*nix systems. Choose your platform below:

<Tabs>
  <Tab title="Ubuntu / Debian">
    ### Install Dependencies

    ```bash theme={null}
    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 libssl-dev zlib1g-dev
    ```

    **Optional:** Install `fuse2fs` for building images without root privileges.

    ### Install GCC 14 or Clang 17+

    A host compiler that supports C++26 features is required. The newer the better.

    #### Option 1: GCC 14

    GCC 14 is available in Ubuntu 24.04 (Noble) and later:

    ```bash theme={null}
    sudo apt update
    sudo apt install gcc-14 g++-14
    ```

    For older versions, use the [ubuntu-toolchain-r/test PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test).

    #### Option 2: Clang 17+

    Recent versions of Clang are available in the [LLVM apt repositories](https://apt.llvm.org/):

    ```bash theme={null}
    sudo apt install libclang-19-dev clang-19 llvm-19 llvm-19-dev
    ```

    ### QEMU 6.2 or Later

    QEMU 6.2 is available in Ubuntu 22.04. For earlier versions, build QEMU from the toolchain:

    ```bash theme={null}
    Toolchain/BuildQemu.sh
    ```

    You may need additional packages to build QEMU:

    ```bash theme={null}
    sudo apt install libgtk-3-dev libpixman-1-dev libsdl2-dev libslirp-dev libspice-server-dev
    ```

    ### CMake 3.25.0 or Later

    <Info>
      The build scripts will automatically build CMake from source if your version is older than 3.25.x.
    </Info>

    If you previously used an older CMake version, remove the cache files:

    ```bash theme={null}
    rm Build/*/CMakeCache.txt
    ```
  </Tab>

  <Tab title="Arch Linux / Manjaro">
    ### Install Dependencies

    ```bash theme={null}
    sudo pacman -S --needed base-devel cmake curl mpfr libmpc gmp e2fsprogs ninja qemu-desktop qemu-system-aarch64 ccache rsync unzip
    ```

    **Optional packages:**

    * `fuse2fs` for building images without root
    * `clang llvm llvm-libs` for building with Clang
  </Tab>

  <Tab title="Windows (WSL2)">
    <Warning>
      You must use WSL2 to build SerenityOS on Windows. Please refer to the [Windows build guide](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructionsWindows.md) for detailed instructions.
    </Warning>

    Once WSL2 is set up, follow the Ubuntu/Debian instructions above.
  </Tab>

  <Tab title="macOS">
    <Info>
      See the [macOS build instructions](https://github.com/SerenityOS/serenity/blob/master/Documentation/BuildInstructionsMacOS.md) for detailed setup steps.
    </Info>
  </Tab>
</Tabs>

## Build and Run

<Steps>
  <Step title="Clone the Repository">
    First, clone the SerenityOS repository:

    ```bash theme={null}
    git clone https://github.com/SerenityOS/serenity.git
    cd serenity
    ```
  </Step>

  <Step title="Build and Launch SerenityOS">
    Run the following command to build and run SerenityOS:

    ```bash theme={null}
    Meta/serenity.sh run
    ```

    This single command will:

    * Download required database files (first time only)
    * Build the SerenityOS cross-compiler toolchain (first time only)
    * Compile all of SerenityOS
    * Install built files into `Build/<architecture>/Root`
    * Build a disk image
    * Start SerenityOS using QEMU

    <Info>
      The chosen architecture defaults to your host architecture. Supported architectures are **x86\_64**, **aarch64**, and **riscv64**.
    </Info>
  </Step>

  <Step title="Log In to SerenityOS">
    When SerenityOS boots, log in with the default credentials:

    * **Username:** `anon`
    * **Password:** `foo`

    <Warning>
      By default, the `anon` user can become `root` without a password as a development convenience. To prevent this, remove `anon` from the `wheel` group.
    </Warning>
  </Step>
</Steps>

## Build Without Running

If you want to test whether your code changes compile without running the VM:

```bash theme={null}
Meta/serenity.sh build
```

## Additional Commands

The `serenity.sh` script provides many other commands. Run it without arguments to see the full list:

```bash theme={null}
Meta/serenity.sh
```

## Troubleshooting

<Accordion title="Build is broken after git pull">
  If the build breaks after pulling changes:

  1. **Rebuild the toolchain** if prompted
  2. **Try with a clean repository** if toolchain rebuild doesn't help
  3. **Ask for help** in the `#build-problems` channel on Discord

  <Info>
    If it builds on CI, it should build for you too.
  </Info>
</Accordion>

<Accordion title="fusermount error during build">
  If you see an error like `fusermount: failed to open /etc/mtab: No such file or directory`:

  ```bash theme={null}
  sudo ln -sv /proc/self/mounts /etc/mtab
  ```

  This creates the missing symlink that `fuse2fs` requires.
</Accordion>

<Accordion title="Toolchain is outdated">
  When updating to a newer compiler, you may need to rebuild the toolchain. See the [troubleshooting guide](https://github.com/SerenityOS/serenity/blob/master/Documentation/Troubleshooting.md#the-toolchain-is-outdated) for details.
</Accordion>

## Installing Ports

To add a package from the ports collection (for example, `curl`):

<Steps>
  <Step title="Navigate to Port Directory">
    ```bash theme={null}
    cd Ports/curl
    ```
  </Step>

  <Step title="Run the Package Script">
    ```bash theme={null}
    ./package.sh
    ```

    The source code will be downloaded and the package will be built.
  </Step>

  <Step title="Launch SerenityOS">
    The next time you start SerenityOS, the port will be available.
  </Step>
</Steps>

### Port Dependencies

Some ports require additional dependencies on your host system. Common requirements include:

```bash theme={null}
# Common dependencies
sudo apt install autoconf automake bison flex gettext gperf help2man \
  imagemagick libgpg-error-dev libtool lzip meson nasm \
  python3-packaging qt6-base-dev rename zip
```

**Special port dependencies:**

* `file` (version 5.44 exactly, for file)
* `libpython3-dev` (for boost)
* `lua` (for luarocks)
* `openjdk-17-jdk` (to compile OpenJDK)
* `p7zip-full` (for msttcorefonts)
* `rake` (to build mruby)

<Note>
  You may need a symlink from `/usr/bin/python` to `/usr/bin/python3` as some ports depend on `python` existing, most notably ninja.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Advanced Build Instructions" icon="gear" href="https://github.com/SerenityOS/serenity/blob/master/Documentation/AdvancedBuildInstructions.md">
    Learn about advanced build options and customization
  </Card>

  <Card title="Contributing Guide" icon="code-pull-request" href="https://github.com/SerenityOS/serenity/blob/master/CONTRIBUTING.md">
    Start contributing to SerenityOS
  </Card>

  <Card title="FAQ" icon="question" href="/faq">
    Find answers to common questions
  </Card>

  <Card title="Documentation" icon="book" href="https://github.com/SerenityOS/serenity/tree/master/Documentation">
    Browse technical documentation
  </Card>
</CardGroup>