How to Install Omarchy on Arch Linux: Complete Setup Guide (2026)

Part of our Omarchy guide

✅ Tested on Omarchy v4.0.0 "Quattro" · Arch Linux · Hyprland · Last updated: August 2026

Arch Linux gives you total control, but that comes with a cost: configuring a complete developer workstation from scratch takes days. Omarchy collapses that into a single command. Read the Omarchy review to understand what the setup includes before installing. You get a fully-configured Hyprland desktop with Neovim, Foot, Docker, built-in AI coding agent support, and the rest of DHH's opinionated toolkit: ready to use immediately after install. This guide covers Omarchy 4.0 “Quattro,” released August 14, 2026, which rewrote the installer and added real dual-boot support.

This guide covers both installation methods: the ISO method (recommended for a dedicated machine) and the manual method (for dual-boot or users who want to start from a vanilla Arch install).

Prerequisites

• A machine with UEFI firmware (Secure Boot and TPM must be disabled)
• A USB drive of at least 4 GB for the installer
• A wired keyboard or USB dongle keyboard: Bluetooth keyboards cannot enter the LUKS encryption password at boot
• A stable internet connection during installation (wired recommended)
• For ISO method with a full-disk install: any drive, but it will be completely wiped
• For ISO method with dual-boot alongside Windows: enough unallocated space on the same drive (shrink the Windows partition first in Disk Management, and disable BitLocker before you start, Omarchy still needs to encrypt with LUKS)
• For manual method: a fresh Arch Linux base system configured as described below

Step 1: Download the Omarchy ISO

Head to omarchy.org and download the latest ISO. As of this writing, the current release is v4.0.0 “Quattro.” Verify the checksum after downloading:

sha256sum omarchy-4.0.0.iso
# Compare against the checksum listed on omarchy.org

Step 2: Create a Bootable USB Drive

Write the ISO to a USB stick. The drive will be completely wiped in the process.

# Linux - replace /dev/sdX with your USB device (check with lsblk first)
lsblk
sudo dd if=omarchy-4.0.0.iso of=/dev/sdX bs=4M status=progress oflag=sync

# Alternative: use the caligula GUI on Linux
# On Windows or macOS: use balenaEtcher (https://etcher.balena.io)

Wait for the dd command to complete and return to the prompt before unplugging the USB stick.

Step 3: Disable Secure Boot and TPM in BIOS

Omarchy will not install with Secure Boot or TPM active. The exact steps depend on your firmware, but the general approach is:

1. Reboot and press the BIOS key at startup (Del, F2, F12, or Esc depending on the manufacturer)
2. Navigate to the Security or Boot section
3. Set Secure Boot → Disabled
4. Set TPM → Disabled (may be listed as PTT, fTPM, or Trusted Platform Module)
5. Save and exit (F10)

On ThinkPads, Secure Boot is under Security → Secure Boot. On ASUS boards, under Boot → Secure Boot Control. On Dell systems, under Secure Boot → Secure Boot Enable.

Step 4: Boot and Run the Installer

Insert the USB stick, boot from it (press the boot menu key: typically F11 or F12), and select the Omarchy USB entry.

Since Quattro, the installer asks you to choose between two install types before anything else:

• Full disk: wipes the selected drive entirely and installs Omarchy alone
• Free space (dual-boot): installs into unallocated space on a drive that already has Windows, leaving your existing installation intact. This only works if you already shrank the Windows partition in Disk Management and disabled BitLocker (see Prerequisites)

After that, it asks the same configuration questions as before:

• Hostname: your machine name (e.g., devbox)
• Username: your user account name
• Password: used for both the user account and the LUKS disk encryption

Omarchy enables full-disk encryption (LUKS) by default on both install types. If you have a specific reason to skip encryption, press Ctrl+C when prompted to confirm disk formatting: this disables encryption for that install. This is the rare exception.

Installation is noticeably faster than previous versions: Omarchy claims 30%+ faster installs since Quattro, and DHH reported 50–56 second installs on Dell and HP laptops shortly after launch. Expect roughly 1–5 minutes depending on your hardware, down from the 2–10 minutes typical of pre-Quattro releases. When it completes, remove the USB stick and reboot.

Step 5: First Boot into Hyprland

At the LUKS password prompt, type your encryption password using your wired keyboard. Bluetooth keyboards will not work here: the Bluetooth stack is not active until after the system decrypts and boots.

After login, Hyprland starts automatically. The desktop is dark and minimal by design: everything is keyboard-driven. Press Super+Return to open the Foot terminal (the default since Quattro, replacing Alacritty) and confirm the system is running:

omarchy --version
# Omarchy v4.0.0

uname -r
# 6.x.x-arch1-1

hyprctl version

Try your default AI coding agent while you are at it: Omarchy 4 wires up nine of them (Claude Code, Codex, Gemini CLI, and more) as lazy-loading commands. Press Super+Shift+Ctrl+A to launch the default one in its own window, or set which agent that is:

omarchy default agent claude   # or codex, gemini, opencode, etc.

Method 2: Manual Installation on Existing Arch

Use this method if you need dual-boot support (requires two physical disks) or prefer to control the base Arch install yourself. Install Arch Linux first with the exact settings below, then run the Omarchy installer on top. Deviating from these settings, especially the filesystem type or bootloader, will break Omarchy.

WiFi During Arch Installation

If you're on WiFi, configure the connection before running archinstall:

iwctl
station wlan0 scan
station wlan0 get-networks
station wlan0 connect "YourNetworkName"
exit

ping -c 3 archlinux.org   # verify connectivity

archinstall Configuration

Run archinstall and configure each section exactly as follows:

Complete the archinstall setup, let it install, then reboot. Log in as your (non-root) user.

Running the Omarchy Installer

curl -fsSL https://omarchy.org/install | bash

The script prompts for your sudo password, then your name and email for git configuration. It then pulls and configures all packages and dotfiles. Allow 5–30 minutes depending on your internet speed. Do not interrupt the process: if it fails midway, re-run the same command and it will resume.

Post-Installation: First Steps

Once Omarchy is running, run these commands before starting any real work:

# Pull the latest Omarchy configs and packages
omarchy update

# Update all Arch system packages
sudo pacman -Syu

# See all available Omarchy subcommands
omarchy help

NVIDIA GPU Setup

Omarchy does not install NVIDIA proprietary drivers automatically. If your machine has an NVIDIA GPU:

sudo pacman -S nvidia nvidia-utils nvidia-settings
sudo reboot

# After reboot, verify driver is loaded
nvidia-smi

AMD GPUs work out of the box via the kernel's built-in amdgpu driver. Intel integrated graphics require no additional setup.

Essential Hyprland Keybindings

Hyprland is entirely keyboard-driven. Learn these before your first session, you'll use them constantly:

All keybindings are defined in ~/.config/hypr/hyprland.conf and are fully editable.

Customizing Omarchy

Omarchy's configurations live in standard dotfile locations, nothing is hidden:

~/.config/hypr/       # Hyprland: keybindings, animations, window rules
~/.config/foot/       # Terminal: font, colors, padding
~/.config/nvim/       # <a href="/neovim-as-an-ai-powered-coding-assistant-on-linux/">Neovim</a> configuration
~/.config/quickshell/ # Bar, launcher, notifications, lock screen - unified since Quattro
~/.config/omarchy/hooks/  # Custom scripts that run on system events (new in Quattro)

Quattro replaced the old Waybar + Walker + Mako + hyprlock combination with a single Quickshell-based shell, so bar/launcher/lock-screen theming now lives in one place instead of four separate config files.

The omarchy unified CLI manages Omarchy-specific operations:

omarchy update    # pull latest Omarchy config updates
omarchy theme     # switch between bundled themes
omarchy help      # list all available subcommands

Because Omarchy is Arch underneath, you have access to the full AUR and official Arch repositories. Install any package with sudo pacman -S package or yay -S aur-package. For SSH key setup and remote access configuration, see the SSH setup guide. For dotfile management across machines, the post-install dotfiles section applies directly to Omarchy too.

Hardware Requirements: What You Actually Need

Omarchy's own documentation doesn't publish a formal minimum spec sheet: no official RAM/CPU/GPU numbers exist. The closest thing to official guidance is a claim on the project's own site that it runs on a 2011 ThinkPad X220 with just 2GB of RAM. Take that as evidence Omarchy itself is lightweight, not as a realistic target for daily use in 2026.

A more useful, reasoned recommendation based on what Omarchy actually runs:

• RAM: 4GB is the honest floor for a usable experience with a browser and terminal open; 8GB+ if you're running Docker (included by default) or any AI coding agent alongside your editor.
• CPU: anything from the last decade works, but a CPU with AES-NI instructions matters more than raw speed here, Omarchy encrypts the disk with LUKS by default, and AES-NI is what keeps that from adding a noticeable read/write penalty.
• GPU: Hyprland is a full compositing Wayland window manager, so it needs real OpenGL/Vulkan support, any GPU from roughly the last 10 years (integrated Intel/AMD included) handles it fine. Very old or exotic GPUs without modern driver support are the actual risk, not raw power.

How Much Disk Space Does Omarchy Need?

Also not published officially. What we can say with certainty: Omarchy installs on top of a full Arch base, adds the Hyprland stack, Quickshell, Neovim, Docker, Foot, and its bundled AI agent CLIs (which don't consume meaningful disk space until you actually pull a model or container image). Budget at least 20GB for the base system with real breathing room, and more if you plan to use Docker images or install a full IDE and toolchains on top.

ARM, Snapdragon and Raspberry Pi Support

Omarchy does not officially support ARM hardware, not Snapdragon laptops, not Raspberry Pi, and not even Apple Silicon Macs. The official manual is explicit about the Mac case: Omarchy has built-in support for Intel Macs, but "installing on an M-series Mac is not directly supported at this time." If Apple's own ARM chips aren't supported, that sets the expectation for Snapdragon and Raspberry Pi too.

Technically, the blocker is upstream of Omarchy: Arch Linux ARM doesn't currently ship a kernel package for Snapdragon X Elite hardware, and Omarchy's package repository only publishes x86_64 builds (the aarch64 repo path returns a 404). Community members have gotten partial results running Omarchy on Apple Silicon under UTM virtualization, around 121 of 148 base packages available, by getting a native Arch Linux ARM install working first, then cloning Omarchy's configuration manually via git rather than using the official installer. That's an experimental workaround, not a supported path. Raspberry Pi has no reported install attempts at all in Omarchy's official channels: the only Pi-related report on record is about Omarchy's built-in rpi-imager tool failing when used from Omarchy to flash a separate device, unrelated to installing Omarchy itself on a Pi.

If you specifically need Hyprland on ARM hardware today, a plain Arch Linux ARM install with Hyprland configured manually is the realistic path, not Omarchy.

Remote Desktop Access on Omarchy

Hyprland is a Wayland compositor, so traditional X11 remote desktop tools (classic VNC servers, xrdp) don't work the same way they did on X11-based setups. Omarchy's official manual only documents the reverse direction: Moonlight streaming from a Windows machine into Omarchy for gaming. For general remote desktop access, the community-verified method is WayVNC, a VNC server built specifically for wlroots-based compositors like Hyprland:

sudo pacman -S wayvnc

# create a virtual headless output for the remote session
hyprctl output create headless VNC-1
hyprctl keyword monitor "VNC-1,1920x1080@60,auto,1"

# start the VNC server on that output
wayvnc -o VNC-1 127.0.0.1 5900

Connect with any standard VNC client pointed at that machine's IP on port 5900. If you specifically need RDP instead of VNC, it's possible via xrdp compiled against a specific GitHub commit plus manual /etc/xrdp/xrdp.ini edits, but the Omarchy community's own consensus is to avoid that route: it's fragile and requires maintaining a non-standard build. WayVNC directly, or the newer hypr-rdp project, are the more maintainable options if you need remote access set up today.

Running Omarchy on Other Platforms

Beyond a standard x86_64 UEFI machine, Omarchy's official manual has a dedicated page (omarchy.org/manual/omarchy-on) documenting alternate platforms: worth reading before you assume something isn't possible. It covers, with varying levels of support:

• Apple Silicon Macs via Asahi Linux: a documented community path, distinct from official direct support. This doesn't contradict the earlier note that M-series Macs aren't "directly supported": it's a documented alternate route through Asahi, not a first-class install target.
• Virtual machines: VirtualBox, VMware Workstation, and Parallels are all documented, useful for trying Omarchy before committing real hardware to it.
• Steam Deck: has its own documented install path.
• A NixOS port of Omarchy: a community project that reimplements Omarchy's configuration as a NixOS flake instead of an Arch install. If you'd rather have Omarchy's Hyprland setup with Nix's declarative reproducibility instead of pacman, this is the bridge between the two ecosystems. See our NixOS installation guide if you want to explore that side first.

Troubleshooting

The installer fails with a "Secure Boot is enabled" error

Reboot into BIOS firmware (press Del or F2 at startup), navigate to the Security section, and set Secure Boot to Disabled. On systems with Windows pre-installed, you may need to clear Secure Boot keys before disabling it. Some ASUS boards require entering the BIOS Setup first, then going to Boot → Secure Boot → Key Management → Clear Secure Boot Keys. Save changes and retry the installer.

My Bluetooth keyboard doesn't work at the encryption password screen

This is expected. The Bluetooth stack initializes only after LUKS decrypts the drive and the OS boots. Use a wired USB keyboard or a keyboard with a USB 2.4GHz wireless dongle (not Bluetooth) to enter the encryption password. Once the system is booted, Bluetooth works normally for everything else.

How do I connect to WiFi during Arch manual installation?

From the Arch live ISO shell, run iwctl to enter the wireless config tool. Then: station wlan0 scan to scan for networks, station wlan0 get-networks to list them, station wlan0 connect "NetworkName" to connect (enter password when prompted). Type exit to leave iwctl. Confirm connectivity with ping -c 3 archlinux.org before proceeding with archinstall.

Omarchy won't boot after installation: black screen

Switch to a virtual terminal with Ctrl+Alt+F2, log in, and inspect the Hyprland log: cat ~/.local/share/hyprland/hyprland.log | tail -50. The most common causes are missing GPU drivers (install nvidia for NVIDIA cards, or verify AMD with lsmod | grep amdgpu) or a corrupted Hyprland config. Reset to Omarchy defaults with omarchy update.

How do I update Omarchy after installation?

Run omarchy update to pull the latest Omarchy configuration changes and packages, then sudo pacman -Syu to update the underlying Arch system. Omarchy releases updates regularly: check the GitHub releases page for changelogs before major updates.

Does the dual-boot installer resize my Windows partition automatically?

No. You need to shrink the Windows partition yourself first, from inside Windows: open Disk Management, right-click the Windows partition, choose “Shrink Volume,” and leave unallocated space for Omarchy. You also need to fully disable BitLocker before booting the Omarchy installer, since Omarchy applies its own LUKS encryption to the new partition and an active BitLocker lock can interfere with the installer seeing the drive correctly. Once that is done, select the “free space” option in the Omarchy installer instead of the full-disk option.

What are the recommended hardware specs for Omarchy?

There's no official minimum from the Omarchy project: the only public data point is that it runs on a 2011 ThinkPad X220 with 2GB of RAM. For comfortable daily use in 2026, budget at least 4GB of RAM (8GB+ with Docker or an AI coding agent running), any GPU from the last decade for Hyprland's compositing, and a CPU with AES-NI so the default LUKS encryption doesn't add a noticeable performance cost.

How much disk space does an Omarchy install use?

No official figure is published. Budget at least 20GB for the base Arch + Hyprland + Omarchy toolkit install, with more room if you plan to use Docker images or install additional development toolchains.

Can I install Omarchy on a Raspberry Pi or a Snapdragon laptop?

No, Omarchy only officially supports x86_64 UEFI hardware. It doesn't even support Apple Silicon Macs yet (Intel Macs only), and Arch Linux ARM itself lacks a kernel package for Snapdragon X Elite hardware. There are no verified Raspberry Pi installs of Omarchy on record.

How do I set up remote desktop access on Omarchy?

Install WayVNC (sudo pacman -S wayvnc), create a headless output with hyprctl output create headless VNC-1, then start the server with wayvnc -o VNC-1 127.0.0.1 5900 and connect with any VNC client. It's the community-standard method since Hyprland doesn't support traditional X11 remote desktop tools.

Can I install Omarchy with /home on a separate drive or partition?

One user-reported issue worth knowing before you plan your partitioning: a separate /home partition or disk has caused problems for at least one documented install, pushing toward keeping everything on a single SSD. This isn't confirmed as a universal limitation of Omarchy itself: if you specifically need a separate /home, test it before committing, and have a single-disk fallback plan.

My screen locks up after configuring a high-refresh-rate monitor

At least one user reported this with a 165Hz+ display after changing Hyprland's monitor configuration. If it happens to you, switch to a TTY with Ctrl+Alt+F3, log in, and edit your Hyprland monitor config back to a known-working refresh rate before returning to the graphical session.

JM Carreira

I’ve used Linux since 2008 and it has been my main system since 2021. When an article has a “Tested on” box, I ran the steps on my Lenovo Tiny. More about me and the test machine.