Prerequisites for Omarchy: Complete Installation Requirements Guide

Omarchy requires an Arch Linux-based system with systemd, the pacman package manager, Quickshell for the graphical interface, and essential command-line tools like git and curl, along with optional components such as snapper and systemd-oomd.

The basecamp/omarchy repository (specifically the quattro branch) provides a complete desktop environment built atop Arch Linux. Before running the installer, your system must satisfy specific prerequisites that the installer verifies through automated checks in bin/omarchy-windows-vm.

Core System Requirements

Omarchy is tightly coupled to Arch Linux conventions and systemd service management. The foundation rests on two non-negotiable components.

Arch Linux Base System

Omarchy assumes the Arch Linux filesystem layout and relies exclusively on pacman for package management. During initialization, the installer checks for the presence of /etc/arch-release and validates that the pacman command is available. Without these, the installation aborts immediately.

systemd Init System

All background services—including systemd-oomd and user-level services used by Omarchy—require systemd. The prerequisite script verifies this by checking for systemctl and confirming that the PID 1 process is systemd.

Required Software Components

Beyond the base operating system, Omarchy depends on several specific tools and runtime environments.

Quickshell UI Runtime

The graphical interface, panels, and menus are implemented as Quickshell plugins. The installer verifies that the quickshell binary exists in $PATH before proceeding, as detailed in shell/README.md.

pacman-guard

Omarchy includes pacman-guard to suppress noisy output from pacman during non-upgrade operations. The installer must locate this guard script and confirm it can be sourced; failure to find it results in installation termination.

Essential Command-Line Tools

The installer probes for standard Unix utilities required for downloading, extracting, and configuring components. These include git, curl, unzip, bash, sed, and awk. Each tool is checked using command -v <tool>; missing utilities trigger a clear error message identifying exactly which package to install.

Optional but Recommended Components

While the system will function without these, they provide critical safety and performance benefits.

snapper for System Snapshots

snapper enables snapshot-based rollbacks for Omarchy configuration and system state. The installer runs snapper --version and verifies that the configuration template in default/snapper/ can be copied. Though optional, omitting snapper removes the ability to roll back system changes.

systemd-oomd for Memory Management

systemd-oomd provides out-of-memory protection for user sessions. A guard script checks for the existence of the systemd-oomd.service unit. While not strictly required, running without it increases the risk of system hangs under memory pressure.

Verification Process

The installer implements rigorous validation logic in bin/omarchy-windows-vm. Each prerequisite check follows a specific pattern:

• Distribution check: Validates /etc/arch-release and pacman availability
• Init system check: Confirms systemctl presence and systemd as PID 1
• Binary checks: Uses command -v to locate git, curl, unzip, and other essentials
• Disk space check: Runs df -h to ensure sufficient free space for the Omarchy package set and user configuration files
• Network connectivity: Performs ping -c1 archlinux.org to verify repository access
• Privilege escalation: Confirms root access or working sudo for writing to /usr/share/omarchy/

If any check fails, the script aborts with a concise error explaining the missing prerequisite and the specific command to remedy it (e.g., "install systemd-oomd via pacman -S systemd-oomd").

Installing Missing Prerequisites

To satisfy all requirements before running the Omarchy installer, install the core packages:

# Install required and optional components

sudo pacman -Syu base-devel git curl unzip systemd-oomd snapper

To verify your system readiness without starting the full installation:

# Check prerequisites manually

bash "$OMARCHY_PATH/bin/omarchy-windows-vm" --dry-run

# Or use the convenience command if already partially installed

omarchy check-prerequisites

The install/config/all.sh file defines the complete package lists (omarchy-base.packages and omarchy-other.packages) that the installer references, while docs/update-process.md documents runtime requirements for the update system.

Summary

• Operating System: Arch Linux or Arch-based distribution with /etc/arch-release and pacman
• Init System: systemd with systemctl available
• User Interface: Quickshell binary in $PATH
• Core Tools: git, curl, unzip, bash, sed, awk (verified via command -v)
• Safety Features: snapper (for snapshots) and systemd-oomd (for OOM protection) recommended but optional
• Resources: Sufficient disk space per df -h and network connectivity verified by ping -c1 archlinux.org
• Permissions: Root access or sudo for system-wide installation to /usr/share/omarchy/

Frequently Asked Questions

Can I run Omarchy on Ubuntu or other Debian-based distributions?

No. According to the source code in bin/omarchy-windows-vm, Omarchy strictly requires an Arch Linux-based system. The installer checks for /etc/arch-release and the pacman package manager; if these are absent, the installation aborts. The dependency on Arch-specific filesystem layouts and systemd service management makes porting to other distributions non-trivial.

Is snapper absolutely required for Omarchy to function?

No, snapper is optional but strongly recommended. As implemented in the prerequisite checks, if snapper --version fails, the installer issues a warning but continues. However, without snapper, you lose the ability to perform snapshot-based rollbacks of your Omarchy configuration, which the update process in docs/update-process.md relies on for safe system modifications.

Why does Omarchy require Quickshell specifically?

Omarchy's graphical interface is architected as a collection of Quickshell plugins rather than using traditional desktop environment components. The installer verifies the quickshell binary exists because the shell components in the shell/ directory depend on the Quickshell runtime and its specific plugin discovery path. Without it, the desktop environment cannot initialize its panels or menus.

What happens if I don't have systemd-oomd installed?

The installation will proceed, but you will lack out-of-memory protection for user sessions. The prerequisite script in bin/omarchy-windows-vm checks for the systemd-oomd.service unit only as a guard condition, allowing the install to continue if absent. However, as noted in the configuration files, running without systemd-oomd increases the risk of system instability when memory is exhausted.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}