To Be revised: Omarchy v2 does not support aarch64 yet

The Guide to Installing Omarchy (Hyprland) on a Raspberry Pi 5
Using the Manjaro ARM Dev Image and install-bare

Discord thread
There is a Discord thread in Omarchy channel at https://canary.discord.com/channels/1390012484194275541/1398487591892025445, if anyone wants to discuss. Thanks

Introductuction

This guide provides a comprehensive, step-by-step process for setting up a minimal and functional Hyprland desktop environment on a Raspberry Pi 5 using the Omarchy dotfiles and installer.

This method uses a development branch of Manjaro ARM. It is intended for enthusiasts who are comfortable with a potentially less stable environment in exchange for newer software and hardware support.

A Note on Other Linux Distributions

At the time of writing, attempts to install a functional Hyprland desktop on the Raspberry Pi 5 using boot images from Arch Linux ARM (both the official image and community installers) have been unsuccessful. These attempts often result in boot failures or an inability to launch the graphical environment. The Manjaro ARM image currently provides the most reliable foundation for this specific hardware and software combination.

Prerequisites

• Hardware:
  • Raspberry Pi 5 (8GB RAM recommended)
  • A quality power supply (5V/5A USB-C PD recommended)
  • A high-speed microSD card (32GB or larger), as of this writing NVME has NOT been tested.
  • Keyboard, mouse, and a monitor
  • An active internet connection (Ethernet is recommended for initial setup)
• Software:
  • The latest Manjaro ARM minimal developer image for the Raspberry Pi.
  • A tool for flashing images to a microSD card, such as Raspberry Pi Imager or BalenaEtcher.

Step-by-Step Installation Process

Step 1: Download and Flash the Manjaro Image

1. Navigate to the Manjaro ARM Raspberry Pi releases page:
   https://github.com/manjaro-arm/rpi4-images/releases
2. Find the most recent minimal image from the "Dev" (development) branch. The filename will look something like Manjaro-ARM-minimal-rpi4-YYYYMMDD.img.xz.
3. Download the image file. You do not need to extract the .xz archive; modern flashing tools can handle it directly.
4. Use Raspberry Pi Imager or BalenaEtcher to flash the downloaded image onto your microSD card.

Step 2: First Boot and Manjaro Initial Setup

1. Insert the microSD card into your Raspberry Pi 5 and power it on.
2. The first boot will initiate Manjaro's OEM (Original Equipment Manufacturer) setup script. You will be guided through a command-line interface to:
   • Set your username.
   • Set your user password and the root password.
   • Choose your timezone and locale (e.g., en_US.UTF-8).
   • Select your keyboard layout.
3. Once the script finishes, it will return you to a login prompt.

IMPORTANT: Log In as Your User
You must now log in with the username and password you just created. Do not log in as root. All subsequent steps should be performed as your regular user.

Step 3: Update Your System

Before installing anything else, ensure your base system is fully up-to-date. This is crucial for system stability and compatibility.

sudo pacman -Syu

If there are any kernel updates, it is highly recommended to reboot the system:

sudo reboot

Log back in as your user after the reboot.

Step 4: Install Omarchy

First, install the necessary tools (git and wget).

sudo pacman -S --needed git wget nano base-devel python-gobject python-poetry-core uwsm

Use this method if the direct install script fails or if you prefer to inspect the scripts before running them.

1. Clone the Omarchy repository into the correct local directory:

   git clone https://github.com/basecamp/omarchy.git ~/.local/share/omarchy

2. Copy install.sh to $HOME, and removing guard.sh, which prevents to use Manjaro image:

   sed -e s/^.*guard.sh$// ~/.local/share/omarchy/install.sh > ~/install.sh

3. Execute the bare installer:

   export OMARCHY_BARE=true
   bash ~/install.sh

Wait for ~30min , depeding on SD card and network speed.

If any issues, troubleshoot.

Critical Post-Installation Configuration

After the installer finishes, do not reboot immediately. You must perform several critical configuration steps to ensure your system is functional, secure, and stable.

1. Address the Display and Rendering Issue (High-Resolution Monitors)

This step is essential for users with 4K or other high-resolution displays to prevent the "black screen" rendering bug caused by hardware limitations.

WARNING; DO NOT use fractional scaling.
As dicussed in Discussion in hyprland: hyprwm/Hyprland#11253, factional scaling does not work.
It would make black waybar and backgound, and unsuable.

1. Navigate to the configuration directory: cd ~/.config/hypr/

2. Open the monitor configuration file: nvim monitors.conf

3. Edit the monitor= line according to your display's resolution.

   • For 4K Monitors (e.g., 3840x2160):
     Fractional scaling is known to fail. The best method is to use a sharp integer scale of 2. This will make the UI large and readable.

     # monitors.conf
     env = GDK_SCALE,2
     monitor=,preferred,auto,2

   • For 1440p Monitors (e.g., 2560x1440):
     These monitors generally work well without scaling.

     # monitors.conf
     env = GDK_SCALE,1
     monitor=,preferred,auto,1

   • For 1080p Monitors (e.g., 1920x1080):
     These monitors work perfectly out of the box.

     # monitors.conf
     env = GDK_SCALE,1
     monitor=,preferred,auto,1
     ```4.  Save the file (`Ctrl+O`, `Enter`) and exit the editor (`Ctrl+X`).
     

2. Install a Functional Web Browser (Brave)

The default browser configured in Omarchy is Chromium. However, the version available for Arch Linux ARM has library mismatches and is unstable. Brave Browser is the recommended, functional alternative.

1. Install Brave from the official repositories:

   sudo pacman -S --needed brave-bin

2. Set default browser:

xdg-settings set default-web-browser brave.desktop

3. Next, update the keybinding to launch Brave instead of Chromium. Open the bindings configuration file:

   nvim ~/.config/hypr/bindings.conf

4. Find the line that defines $browser (around line 18).

5. Comment out the chromium line and add a new line for brave, as shown below:

   # ... inside bindings.conf ...
   
   # Applications
   $terminal = uwsm app -- alacritty
   # $browser = uwsm app -- chromium --new-window --ozone-platform=wayland  # <-- Comment this out
   $browser = uwsm app -- brave --new-window --ozone-platform=wayland      # <-- Add this line
   $webapp = $browser --app

6. Save the file.Now, pressing SUPER + B will correctly launch Brave.

3. Fix the Screen Locker (Replace hyprlock with hyprlock-git)

The default hyprlock package installed by install-bare is known to crash on this setup, preventing the screen from locking correctly and potentially requiring a system restart if triggered by idle timeout. You must replace it with the more up-to-date -git version.

1. First, uninstall the broken hyprlock package.

   sudo pacman -Rns hyprlock

2. Next, install hyprlock-git using yay. When yay asks if you want to replace dependencies or resolve conflicts during the build process, always answer "yes" (Y).

   yay -S hyprlock-git

   This process will compile the latest version of hyprlock from source, ensuring it is compatible with your system.

Final Reboot

Now that the display, browser, and screen locker configurations are corrected, reboot your system to launch into your new Hyprland desktop.

sudo reboot

Your Raspberry Pi 5 should now boot into a functional and stable Hyprland session.

Optional: Installing Additional Software from xtras.sh (Advanced)

The Omarchy setup includes a script at ~/.local/share/omarchy/install/xtras.sh designed to install a full suite of recommended applications.

CRITICAL ADVISORY FOR RASPBERRY PI USERS:

DO NOT RUN THIS SCRIPT DIRECTLY. (./install/xtras.sh)

This script was designed for powerful x86_64 desktop PCs. On a Raspberry Pi, running it blindly will cause significant problems including installation failures, extreme compilation times, massive disk space usage, and accelerated wear on your microSD card.

Instead of running the whole script, you should treat it as a menu and install applications one by one.

How to Install Applications Individually

1. Open the xtras.sh script in a text editor to view the installation commands:

   nvim ~/.local/share/omarchy/install/xtras.sh

2. Find the line for the application you want (e.g., yay -S --noconfirm micro).
3. Copy only that command and paste it into your terminal, removing the --noconfirm flag so you can review the package details before installation.

   yay -S micro

Application Compatibility and Risk Assessment

Use the following table to make an informed decision about which applications to install.