How to Install the Omarchy Linux Distribution: Complete Setup Guide

Omarchy installs from a bootable ISO that runs a guided installer supporting full-disk, dual-boot, and unattended modes, with LUKS encryption enabled by default and automated post-install configuration via a first-boot wizard.

To install Omarchy, you download a bootable ISO from the basecamp/omarchy repository, write it to USB, and boot into the graphical installer. The installation process handles partitioning, encryption, and initial user setup automatically, leaving you with a ready-to-use Arch-based desktop environment.

Prerequisites and ISO Preparation

Omarchy distributes itself as a complete bootable image. The ISO contains the base system, installer logic, and package definitions found in install/omarchy-base.packages.

Downloading the Official ISO

Download the latest Omarchy release from the official GitHub releases page. The ISO includes all packages necessary for the base system, eliminating the need for network installation.

Creating Bootable Media

Write the ISO to a USB stick using dd or your preferred imaging tool. Replace /dev/sdX with your actual device identifier:

sudo dd if=omarchy-2.0.iso of=/dev/sdX bs=4M conv=fdatasync status=progress

Boot your target machine from this USB to launch the Omarchy installer UI.

Installation Methods

The Omarchy installer supports three distinct installation modes, each defined in the repository's manual pages under the manual/ directory.

Full-Disk Installation

This is the default and recommended installation path. The installer wipes the entire drive and creates a LUKS-encrypted partition, installing Omarchy as the sole operating system.

To start a full-disk install:

omarchy installer start

By default, the target partition uses LUKS encryption. If you require an unencrypted install (not recommended), deselect the encryption option during the partitioning step of the graphical wizard.

Dual-Boot Installation

For systems running Windows or another Linux distribution, Omarchy supports installation into free space without destroying existing partitions. This process is documented in manual/50-dual-boot-install.md.

First, shrink your existing partition to create unallocated space. Then launch the installer with the free-space flag:

omarchy installer start --free-space

The installer creates a new LUKS-encrypted partition in the available space and configures the bootloader to preserve your existing OS.

Unattended Installation

For automated deployments, Omarchy supports fully unattended installs using a cidata drive containing pre-generated configuration files. Place user_credentials.json and optional tailscale_authkey files on a separate USB or partition.

Trigger the automated workflow with:

omarchy installer start --auto

The installer reads the configuration, partitions the disk, encrypts the volume, and creates the user account without displaying the graphical wizard. Complete specifications are available in manual/51-unattended-installs.md.

Post-Installation Configuration

After the installer completes and the system reboots, Omarchy presents a first-boot wizard to finalize configuration.

First-Boot Wizard

The graphical wizard performs the following actions:

• Creates your user account (username and password)
• Sets the LUKS drive-encryption password (if encryption is enabled)
• Optionally imports SSH authorized_keys for remote access
• Optionally configures Tailscale using a provided auth-key

The wizard writes configuration files to /etc/omarchy-edition and /etc/skel, which subsequent migration scripts and the omarchy-reinstall command reference to maintain system state.

System Updates with omarchy-update

Keep your installation current using the built-in update command. According to manual/30-updates.md, omarchy-update pulls the latest packages from the Omarchy Arch mirror and applies pending system migrations:

omarchy-update

This command ensures you receive security patches and feature updates specific to the Omarchy distribution.

Package Management

Install additional software using the Omarchy package helper. The command references package lists defined in install/omarchy-other.packages for optional components:

# Install Joplin note-taking application from AUR

omarchy pkg add joplin-bin

This integrates with the standard Arch package manager while maintaining Omarchy's configuration overlays.

System Reset and Reinstallation

If you need to restore the system to its post-install state while preserving the base system, use the reset functionality. The Setup > Reset Computer menu entry or the command-line tool restores the baseline snapshot created by the installer:

omarchy-reinstall

This wipes user data and configurations but preserves the encrypted partition structure and base system packages defined in install/omarchy-base.packages, effectively returning the machine to a fresh-install state without requiring USB media.

Summary

• Omarchy installs from a bootable ISO that includes all base packages and a graphical installer.
• Three installation modes are available: full-disk (default), dual-boot using --free-space, and unattended using --auto with a cidata drive.
• LUKS encryption is enabled by default for all installation modes, with an option to disable during partitioning.
• Post-install configuration occurs via a first-boot wizard that handles user creation, encryption passwords, SSH keys, and Tailscale setup.
• System maintenance uses omarchy-update for updates and omarchy-reinstall for resets, both documented in manual/30-updates.md and the installer source files.

Frequently Asked Questions

Does Omarchy require manual partitioning during installation?

No. The Omarchy installer handles partitioning automatically. For full-disk installs, it creates the necessary partitions and encrypted volumes without user intervention. For dual-boot scenarios, you must first free up space using your existing OS's disk management tools, then the installer automatically utilizes that unallocated space when run with --free-space.

Can I disable disk encryption when installing Omarchy?

Yes, though it is not recommended. The installer enables LUKS encryption by default for all installation modes. During the partitioning step of the graphical wizard, you can deselect the encryption option to proceed with an unencrypted install. Note that this reduces security and is generally discouraged for production systems.

What files does Omarchy modify during the first-boot wizard?

The wizard writes configuration data to /etc/omarchy-edition and populates /etc/skel with default user templates. These files are later referenced by omarchy-reinstall and migration scripts during system updates to ensure consistency between the base system and user environments.

How do I perform an unattended installation of Omarchy?

Create a cidata drive containing user_credentials.json and optional authentication files like tailscale_authkey. Boot the Omarchy ISO with this drive attached, then execute omarchy installer start --auto. The installer reads the configuration, partitions the disk, applies encryption, and completes setup without displaying the graphical interface. Full specifications are documented in manual/51-unattended-installs.md.

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