What Is Omarchy Based On? Arch Linux, Hyprland, and Quickshell Explained

Omarchy is built on three core technologies: Arch Linux as its rolling-release base, Hyprland as its tiling Wayland compositor, and Quickshell as its desktop construction kit for widgets and panels.

Omarchy is an omakase Linux distribution that combines these three components into a cohesive, minimal desktop environment. According to the omaccom/omarchy source code, this architecture delivers a bloat-free foundation with a polished, theme-rich user experience.

The Three Pillars of Omarchy

Arch Linux: The Rolling-Release Foundation

Omarchy inherits its package management, system libraries, and ecosystem from Arch Linux. This choice provides several advantages:

• Access to the Arch User Repository (AUR) and pacman package manager
• Rolling-release updates without major version upgrades
• Minimal base installation with only required components

The repository's README.md explicitly states this dependency, and the project uses standard Arch tooling throughout its configuration files.

Hyprland: The Tiling Wayland Compositor

Hyprland provides Omarchy's window management. This modern Wayland compositor delivers:

• Smooth animations and hardware-accelerated rendering
• Extensive customization through configuration files
• Tiling window layout with floating capabilities

Key configuration lives in config/hypr/hyprland.lua, where Omarchy defines its default window rules, keybindings, and compositor behavior. The bin/omarchy-theme-set helper script synchronizes Hyprland's appearance with the active Omarchy theme.

Quickshell: The Desktop Construction Kit

Quickshell serves as the "desktop construction-kit" that powers Omarchy's UI layer. As documented in manual/01-welcome-to-omarchy.md, Quickshell supplies:

• The top panel and system widgets
• Global shortcuts and menu systems
• Integration layer between Hyprland and user applications

The default/omarchy/omarchy-menu.jsonc file demonstrates this integration—it defines menu structures that tie Quickshell widgets directly to Omarchy commands.

Working with Omarchy's Base Components

Checking Version and Reloading Configuration

# Display current Omarchy version (relies on Arch package base)

omarchy version

# Reload Quickshell after editing widgets or panels

omarchy-reload

Switching Themes Across Both Compositors

# Apply the "sol" theme to both Hyprland and Quickshell simultaneously

omarchy-theme-set sol

The omarchy-theme-set helper ensures visual consistency by updating configurations for both Hyprland and Quickshell in a single operation.

Key Integration Files

Understanding these files clarifies how Omarchy weaves its three base technologies together:

File	Purpose
config/hypr/hyprland.lua	Default Hyprland window manager configuration
default/omarchy/omarchy-menu.jsonc	Quickshell menu definitions linking widgets to commands
bin/omarchy-theme-set	CLI utility for synchronized theme changes
manual/01-welcome-to-omarchy.md	Official documentation stating the Arch+Hyprland+Quickshell architecture

Why This Architecture Matters

Omarchy's triple-base design offers distinct trade-offs. Arch Linux provides bleeding-edge software at the cost of occasional manual intervention. Hyprland delivers modern Wayland performance while requiring compatible hardware and applications. Quickshell enables deep customization through code rather than graphical tools.

This stack prioritizes users who value control and minimalism over out-of-the-box convenience. The omarchy-theme-set utilities and omarchy-reload helpers abstract some complexity, but the underlying components remain exposed for direct modification.

Summary

• Omarchy is based on Arch Linux, Hyprland, and Quickshell according to official project documentation in manual/01-welcome-to-omarchy.md
• Arch supplies the package ecosystem and rolling-release foundation
• Hyprland handles window management as a modern Wayland compositor
• Quickshell provides the desktop shell with panels, widgets, and shortcuts
• Configuration spans config/hypr/hyprland.lua for window rules and default/omarchy/omarchy-menu.jsonc for UI definitions
• Helper commands like omarchy-theme-set and omarchy-reload coordinate changes across all three layers

Frequently Asked Questions

Is Omarchy a standalone Linux distribution or an Arch derivative?

Omarchy is an Arch derivative rather than a standalone distribution. It uses Arch Linux as its complete base system, including the pacman package manager, kernel, and system libraries. The project adds curated Hyprland configurations, Quickshell widgets, and helper utilities on top of standard Arch.

Can I use Omarchy without knowing how to configure Hyprland manually?

Yes. Omarchy provides sensible defaults in config/hypr/hyprland.lua and theme management through omarchy-theme-set. However, the project expects users to eventually engage with configuration files directly, as this aligns with its "omakase but hackable" philosophy documented in the welcome manual.

What happens if I want to replace Quickshell with another desktop environment?

Quickshell is deeply integrated into Omarchy's default experience. The default/omarchy/omarchy-menu.jsonc file and various helper scripts assume its presence. Removing it would require significant manual reconfiguration of menus, panels, and theme synchronization that omarchy-theme-set currently handles automatically.

Does Omarchy support NVIDIA graphics given Hyprland's Wayland requirements?

Hyprland's NVIDIA support has improved significantly, but remains more complex than Intel or AMD configurations. Check the config/hypr/hyprland.lua file for any Omarchy-specific workarounds, as the project may include tailored settings for proprietary driver compatibility.

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