Omarchy Desktop: Installation, Development, and Safe Maintenance
Omarchy is a Linux desktop system with its components, appearance, and operating conventions already chosen. It suits people who want to develop locally, use a terminal, and learn a keyboard-oriented workflow. Installing it changes the computer's operating environment; it is more than a visual theme for an existing desktop.
This guide helps you decide whether to install it, complete a small local project, and handle updates, customization, and recovery. If Omarchy is already installed, start with “Your first desktop session.” Before replacing a working computer's system, complete the backup and installation-mode decisions first.
What Omarchy, Arch Linux, and Hyprland each do
The current official manual describes a desktop integrating Arch Linux, Hyprland, and Quickshell:
Wayland is a protocol through which Linux graphical applications communicate with the display system. A compositor arranges windows and presents their contents on screen. A terminal is an application for entering commands; the program interpreting those commands is a shell. Despite its name, Quickshell provides the desktop interface here, rather than interpreting terminal commands.
Arch continually updates packages instead of limiting upgrades to occasional major distribution releases. Omarchy adds its own release and update arrangements. Using Arch packages therefore does not mean every Arch tutorial applies unchanged.
Choosing a desktop
This table offers decision criteria, not a ranking of speed, stability, or security.
List the functions you must retain: video meetings, composition input, external displays, suspend, and specialist applications. Prefer testing on a spare device or in a recoverable test environment before replacing your working system. Similar-looking desktops do not establish compatibility. This guide does not give unverified minimum RAM, CPU, or storage requirements, or promise support for every laptop.
Version baseline
As of 2026-09-12, the official latest-release API reported stable v4.0.3, published on 2026-09-08 at 19:50:46 UTC, not a prerelease. The API redirects to the current omacom/omarchy repository. This is a dated release observation; check the release page again before installing.
This guide follows v4's Lua configuration, Quickshell, and Foot terminal. Do not transplant older instructions for hyprland.conf, Waybar, or legacy vendor directories. The Omarchy version also does not establish the kernel, Hyprland, or graphics-driver version. On an existing v3 system, back up and consult the applicable official migration instructions rather than constructing a migration from this page's file paths.
Before installation: decide which disk may change
Prepare a recoverable environment
Use the official installation instructions during the actual installation. Have these ready:
- A target computer capable of booting the installation USB, reliable power, and a usable network connection.
- A USB drive whose contents may be replaced; writing the ISO image replaces its existing contents.
- An identified target physical disk. Record its model, capacity, and purpose rather than relying on “the first drive.”
- File backups independent of the target disk, plus the installation media and recovery material needed to restore the previous system.
- A wired keyboard or one with a 2.4 GHz receiver. The manual says Bluetooth keyboards cannot unlock the preboot disk-encryption prompt.
Back up personal files, uncommitted project changes, and configuration you need to retain. Restore a sample file from the backup before proceeding. Keep encryption keys and recovery material private; never include them in support logs.
Full disk or free space
The current installer offers two distinct routes:
Both routes enable disk encryption by default. Encryption primarily protects stored data when the computer is off; it neither backs up files nor replaces access controls in an unlocked session. Keep the default unless you understand the consequences of changing it. Installation modes and encryption defaults
Firmware settings: Secure Boot and TPM
Secure Boot verifies boot software. A TPM is a hardware security component that can store keys and participate in device-security checks. Neither technology is exclusive to Windows.
Omarchy's current installation manual requires disabling Secure Boot and/or TPM before installation. Treat this as a requirement of this installation workflow, not a general rule for Linux. Changing these settings can affect another system's boot or disk-unlock process. Consult the existing OS and device manufacturer's recovery guidance first. Do not clear the TPM or experiment with firmware security settings without a recovery plan. On an organization-managed device, confirm that such changes are permitted. Official installation requirements
From ISO to first boot
An ISO is an image of the installation media. These steps write to storage devices; they are not a non-destructive trial:
- Follow the download link from the official installation page or release page, rather than using an unofficial repackaged image.
- Use the manual's image-writing tools: balenaEtcher on macOS / Windows, or caligula on Linux. Obtain them through the official references.
- Recheck the target USB's model and capacity in the image-writing tool. Confirm that it contains nothing you need before writing the image.
- Open the computer's boot menu using the manufacturer's instructions and boot the USB. If this fails, check the selected boot device and the manual's firmware requirements before changing unrelated disk settings.
- Select the previously identified target disk and installation mode. Read the final confirmation carefully. Cancel if it does not match your disk plan.
- Complete the installer prompts and restart into the installed system when instructed. Retain the USB as possible recovery media.
Writing the installation USB and installing onto the computer's disk are separate device-selection steps. Choosing the right USB does not automatically select the right system disk later; verify the target both times.
The separate Windows dual-boot route
The official Windows dual-boot procedure requires turning off BitLocker / device encryption and waiting for decryption to finish. Then shrink the volume in Windows Disk Management, leaving unallocated space. Confirm encryption status and recovery material from Windows; merely seeing a partition from Linux is not sufficient preparation.
Boot the Omarchy USB, select the physical drive, and choose Free space install. The manual's 50 GB is an example, not a minimum-capacity guarantee. Allow for your applications, projects, and future data. Omarchy's side still defaults to LUKS disk encryption.
The current manual uses the Limine boot manager and documents limine-scan for discovering Windows Boot Manager. This command changes boot configuration; it is not a read-only check to run casually. Use it only within the matching documented procedure. Seeing both systems in a boot menu does not establish that every disk layout is safe.
Your first desktop session
Aim to open the menu, find an application, use a terminal, and return to the menu. You do not need to memorize a full shortcut sheet.
- Unlock the disk with your prepared keyboard and enter the desktop.
- Press Super+Space to open the Omarchy menu. Super is the Windows-logo key on many PC keyboards; the actual mapping depends on your configuration.
- Check the network and volume through the top-bar panels. Inspect Setup > Input before treating a keyboard-layout problem as a broken shortcut.
- Find and open the default terminal, Foot, through the desktop's application interface. Use the menu to orient yourself rather than borrowing a launch shortcut from a different Hyprland configuration.
- Open an installed application, perform a simple task, close its window, and reopen the menu.
- Visit Setup > Keybindings to inspect the bindings installed on this machine. Learn the useful ones as needed.
These menu entries are documented in Updates and Dotfiles; network and sound panels are covered in The top bar. The current top-bar manual also documents Super+Ctrl+D for the display panel and Super+Shift+Space to toggle the bar. If the bar disappears, check whether it was toggled before resetting configuration.
Orient yourself in the terminal
These commands read local state, install nothing, and need no sudo:
cat /etc/os-release
uname -r
printf '%s\n' "$XDG_SESSION_TYPE"
pacman -Q omarchy
pacman -Qs foot
The first two show operating-system information and the running kernel version. The session variable normally reads wayland in a Wayland desktop session, but does not prove that every application uses native Wayland rendering.
pacman -Q omarchy queries a locally installed package with that name. If the package is not found, check the actual packaging and system version; that alone does not mean Omarchy is absent. pacman -Qs foot searches installed-package names and descriptions without refreshing repository databases. Your output need not match someone else's screenshot exactly.
Practice: write and test a small local program
This exercise connects the terminal, files, and tests without installing software, using the network, or changing system configuration. It uses sh and ordinary file tools, so it does not depend on a particular language runtime being preinstalled. Everything stays in a newly created personal directory.
1. Check the tools and create a practice directory
Check each command in Foot:
command -v sh
command -v mktemp
command -v cat
Each should print a command path. Empty output or a nonzero exit status means the current shell did not resolve that command. If a tool is missing, stop and inspect the local environment rather than pasting an installation script from an unfamiliar website.
Create a new directory with a random suffix, avoiding existing projects. Keep using the same terminal:
project_dir=$(mktemp -d "$HOME/omarchy-practice.XXXXXX")
Success normally produces no output. Enter the directory:
cd -- "$project_dir"
pwd
pwd should show a directory under your home directory named omarchy-practice. followed by a random suffix. If creation or cd fails, stop rather than running the next step in an unknown directory. The variable exists only in the current shell; use the path printed by pwd to reopen the project later.
2. Write the program
cat > greet.sh <<'EOF'
#!/bin/sh
name=${1:-Omarchy}
printf 'Hello, %s!\n' "$name"
EOF
sh greet.sh
sh greet.sh 'Linux learner'
Expected output, in order:
Hello, Omarchy!
Hello, Linux learner!
greet.sh is the program file. ${1:-Omarchy} uses the first argument when it is supplied and nonempty, otherwise the default name. Quoting the name containing a space passes it as one argument. Running sh greet.sh does not require changing the file's executable permissions.
The quoted delimiter after cat preserves the program text instead of expanding its variables while writing the file. The > operator replaces a file with the same name, which is why this exercise belongs in the new directory.
3. Test both behaviors
A test checks an explicit expected result rather than merely looking for the absence of errors.
cat > test-greet.sh <<'EOF'
#!/bin/sh
set -eu
test "$(sh ./greet.sh)" = 'Hello, Omarchy!'
test "$(sh ./greet.sh 'Linux learner')" = 'Hello, Linux learner!'
printf '%s\n' 'PASS: default and named greetings'
EOF
sh test-greet.sh
Expected output:
PASS: default and named greetings
test compares actual output with the expected text. Here, set -e stops the script on a failed test, while set -u helps detect unset variables. The script prints PASS only after both checks succeed.
If a program file is missing, use pwd and ls to confirm that both files are in the same directory. If the output differs, run sh greet.sh separately and check punctuation and spacing. Do not simply remove a check to obtain a passing result.
You can now open greet.sh in an editor, change its greeting, and rerun the tests to see the effect. Keep the two small files; no cleanup command is needed. To start recording project history, continue with Git and GitHub. For editing, see Vim.
Moving to a real development project
Check what is available instead of assuming every development stack is preinstalled:
command -v git
command -v python
command -v uv
command -v node
command -v docker
An unresolved command does not mean Omarchy installation failed. Choose the language your project needs, then prepare it using that tool's official instructions. There is no need to install every compiler, database, and service at once.
For Python, follow the uv environment guide to keep dependencies in a project environment. Do not use sudo pip or install application dependencies into system Python. Finding docker proves only that the client command exists, not that its service is running or your user can access it. Avoid arbitrary system-permission changes merely to make an example run.
For persistent terminal work, see tmux. For remote hosting, use Personal VPS Fundamentals: Omarchy here is the local desktop, while the VPS is another system. Keep their update and firewall commands separate. Passwords, access tokens, and private keys do not belong in examples, shared configuration, or shell history.
System updates and software packages
Use the Omarchy updater
A full update coordinates the system and its dependencies. Omarchy also needs its own migrations and configuration handling. The official update manual presents Update > Omarchy and this command as the same supported path:
omarchy update
This command changes the installed system. Save your work, confirm an independent backup is usable, and leave time for errors and a possible restart. Do not run another package transaction concurrently. The workflow handles the Omarchy release, migrations, system / AUR updates, and a snapshot. Follow its output, then check the applications you rely on.
Current Omarchy is installed through regular pacman packages, not merely copied configuration on top of a separately managed desktop. The manual says stable is the default channel, follows official releases, and uses an Omarchy mirror one month behind upstream Arch. This is the current update policy, not a permanent promise or a security-response deadline.
Direct pacman -Syu or yay -Syu operations bypass Omarchy's snapshot, migration, and configuration workflow; the current manual describes them as guarded paths. Do not bypass those protections or replace the supported updater because another Arch tutorial uses these commands. Firmware has a separate Update > Firmware workflow using fwupd and may require a restart. Not every device necessarily offers firmware updates there.
Why refreshing only the package list is unsafe
pacman is Arch's underlying package manager. Repository databases describe available packages and versions; installed packages are the files your machine currently uses. Refreshing only the databases and then installing selectively can introduce software that needs newer libraries than the installed system provides.
Arch explicitly does not support partial upgrades. Do not run pacman -Sy or pacman -Sy package. If a transaction fails after synchronization, resolve the problem and complete the full update before other package operations. Arch's general maintenance advice explains the risk but does not replace Omarchy's update workflow.
Official packages and the AUR
The AUR, or Arch User Repository, contains community-maintained build instructions. It is not the same trust source as official repositories. Installation can execute those instructions; an AUR helper or a popular package does not replace inspection. Read the build files and sources first, and defer installation if you cannot assess them. Changes to system libraries' binary interfaces can also require rebuilding some AUR packages. Arch maintenance guidance
Use these commands to inspect local package state:
pacman -Qs foot
pacman -Qm
The first searches installed-package information. The second lists foreign packages absent from the current sync repositories. They may come from the AUR or elsewhere, so this is not strictly an “AUR list.” Neither command installs software or refreshes databases.
The Joplin example below uses the exact Omarchy package-add command documented in the manual. It is optional, not a prerequisite for learning the desktop. Review community build instructions where applicable instead of substituting an unchecked generic installation command.
Customization: know which files you own
The current dotfiles manual puts user configuration under ~/.config and vendor files under /usr/share/omarchy. Do not edit the vendor directory directly: upgrades can replace it, and such edits make problems harder to trace.
Abbreviated filenames in the table also live under ~/.config/hypr/. The manual says personal aliases and functions in .bashrc are not overwritten; still keep backups of important changes.
Prefer Setup > Monitors / Keybindings / Input / Config to open the relevant editor. These entries handle the required restart after editing. The default editor is Neovim: normal mode is for text operations; press i to enter insert mode. After editing, press Esc, type :wq, and press Enter to save and quit. Use :q! to discard unsaved changes. See the Vim guide for more editing help.
A reversible example: bind a key to Joplin
Do this only if you actually want Joplin. The official configuration page supplies this package command and Lua example. First confirm you are on v4 and that ~/.config/hypr/bindings.lua exists. If it is absent, stop instead of inventing a new-version configuration.
-
Prepare a fully updated system, inspect the relevant package's build instructions, and install the application. This changes the system:
omarchy-pkg-add joplin-bin -
Open Joplin from the application interface first. If it cannot run directly, solve the application problem before changing a shortcut.
-
Make a local copy of the existing bindings file:
cp -i -- ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-editIf the destination already exists,
-iasks before overwriting it. Do not overwrite your only known-good copy; cancel and choose another filename if you need to keep it. This is a configuration copy on the same disk, not a disaster-recovery backup. -
Open Setup > Keybindings and inspect the current action for Super+Shift+O. Add the manual's example only if you accept replacing that action:
hl.unbind("SUPER + SHIFT + O")o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop") -
Save and exit, let the menu workflow handle reloading, and press the combination. Joplin should open. If it opens directly but not through the binding, check spelling, duplicate bindings, and reload errors.
To undo the edit, first confirm the copy contains the old state you want, then run:
cp -i -- ~/.config/hypr/bindings.lua.before-edit ~/.config/hypr/bindings.lua
This replaces the current file, also undoing any other changes made since the copy. Then save and exit through the same Setup entry to complete its corresponding reload. Restoring the binding does not uninstall Joplin.
Top-bar and terminal details
A custom shell.json replaces the defaults rather than recursively merging with them. New default widgets therefore do not automatically appear in your customized bar. If a widget is missing after an update, compare configuration before assuming the update failed. Top-bar configuration rules
omarchy bar defaults restores the default bar configuration and discards the corresponding customization; it is not a harmless diagnostic. Save what you need before using it. When changing Foot fonts, evaluate a newly opened terminal window: existing windows do not reload font changes. Display configuration guidance
Troubleshooting displays, input, and hardware
HiDPI and multiple monitors
HiDPI means a display has a high pixel density. Scaling keeps text and controls at a usable size. Start with the display panel instead of copying output names from someone else's configuration. Inspect the actual outputs:
hyprctl monitors
The monitor manual documents the display panel, the Hyprmon terminal interface, and Setup > Monitors, which edits monitors.lua using hl.monitor rules. Record real output names, available modes, and current scaling. Change one display at a time and confirm it remains usable before adjusting another. Obtain Lua rule syntax from the current manual; renaming an old Hyprland configuration file does not convert its syntax.
A listed external screen with no usable picture is different from an output that is not detected at all. For the former, check enablement, mode, and layout; for the latter, inspect connections, docks, and driver information. With mixed pixel densities, use fresh application windows to check text size and behavior when moving between screens. No single scaling value suits every display.
Monitor scaling and GDK_SCALE are different controls. The latter is an integer scaling setting used by some GTK applications. Do not stack global scaling variables to fix one application before determining whether the problem affects the entire desktop or only that application.
Screen sharing, input methods, and NVIDIA
These features depend on applications, drivers, and the component versions packaged by Omarchy. Narrow the symptom and consult applicable documentation before replacing multiple components.
Wayland applications often request screen sharing through desktop portal services, which let the desktop ask the user which screen or window to share. A missing picker and a black image after selection call for different investigations, not immediate package replacement. Further reading: Hyprland screen sharing, Hyprland NVIDIA, and Arch Fcitx5. These are upstream troubleshooting starting points, not recipes verified for every Omarchy v4 device. Check your component versions and Omarchy's integration before adopting specific steps.
Collect a small, useful diagnostic record
These ordinary local checks are read-only and require no sudo:
cat /etc/os-release
uname -r
printf '%s\n' "$XDG_SESSION_TYPE"
hyprctl monitors
systemctl --user --failed
journalctl --user -b -p warning --no-pager -n 80
The last two show failed user services and at most 80 user-log entries at warning severity or higher from the current boot. No failed services does not prove an application is healthy, and not every warning requires a fix. Run hyprctl within a working Hyprland session; failure to connect from a recovery terminal alone does not establish a GPU fault.
When asking for help, include the action, expected result, actual symptom, last change, and a small relevant log excerpt. Logs can contain usernames, file paths, network identifiers, and application details. Inspect and redact them locally before sharing. Do not upload an entire configuration directory, credentials, or unrelated logs.
Recovery: match the remedy to the failure
A small edit, a bad update, and a failed disk need different protection:
Omarchy's updater creates a snapshot, and the manual recommends trying a previous snapshot after a bad update. The official update and recovery guidance does not thereby guarantee coverage of every home-directory file or a fixed snapshot retention count. Snapshots on the same drive remain vulnerable to that drive's failure.
Work from the narrowest applicable remedy:
- Record the symptom and last change. Stop adding unrelated repair commands.
- If you just edited one configuration file and still have a usable session, restore that file and reload through its corresponding workflow.
- For a failure immediately after an update, follow the manual to select a previous snapshot at boot. Check the affected work functions after starting it before deciding what to do next.
- If the normal boot path is unavailable, use retained recovery media and the applicable official instructions. Do not guess at partition changes, bootloader rewrites, or recursive system-permission changes.
- Consider reset or reinstall options only after preserving personal configuration and understanding what they reset.
omarchy reinstall is a reset operation: it can overwrite user configuration, return to stable, and downgrade packages that are too new. Treat Update > Config and omarchy reinstall configs as configuration-changing operations too, not first responses to a small problem. Before installation, major updates, or resets, keep important work outside the target disk and confirm that at least one sample file can be restored.