Omarchy is a keyboard-first Linux desktop built on Arch Linux, Hyprland, and Quickshell. This independent guide explains installation, shortcuts, input, AI agents, updates, and recovery.
Omarchy is a complete desktop experience built on Arch Linux. It uses Hyprland for tiled window management and, in the Quattro generation, Quickshell to unify the bar, launcher, notifications, panels, and plugins. It is not a conventional Linux desktop with a different wallpaper. Its defaults make keyboard launching, automatic window placement, task-oriented workspaces, terminal tools, and a coherent visual system part of one workflow. Understanding those choices matters more than copying an installation command.
This independent Omarchy guide begins with the jobs a user must complete. Installation coverage starts with backups, boot media, disk targets, Secure Boot, dual boot, and first-boot checks. Workflow pages explain the Super key, windows, workspaces, screenshots, clipboard history, themes, and common applications. Maintenance pages then cover updates, snapshots, logs, and recovery. Risky steps include a verification point and a way back, because a command returning successfully does not prove that the whole task is safe or complete.
Chinese and English versions are maintained together, with Windows and macOS action mappings for people moving from familiar systems. You do not need to memorize every shortcut or replace your main computer on day one. Start by learning what Omarchy is, test it in a virtual machine or on spare hardware, and continue only when your software, devices, and recovery plan work. Official releases and manuals remain authoritative for version facts; this site turns that material into a searchable learning path.
Check the installed version before using a tip. As of 2026-10-02, GitHub Releases lists v4.0.4 as the latest stable release. These recommendations combine tagged release notes with the current official manual. The rolling manual may describe features newer than your installed package; verify local menus and CLI help first.
Version 4.0.3, released on 2026-09-08, added Hermes, OpenClaw, Cursor CLI, and more AI tools. Version 4.0.4, released on 2026-09-15, made linux-omarchy the default boot kernel. Responsiveness, Btrfs operations, and compatibility improvements are claims from the official release notes; this guide has not independently benchmarked them.
Source: the official Omarchy v4.0.4 release notes
You can upgrade existing machines with Update > Omarchy.
Finish Update → Omarchy, reboot when you have time to recover, then compare uname -r with pacman -Q linux-omarchy. An installed kernel package and a running kernel are different facts: a successful package update can leave the old kernel running until reboot. Keep the update output and test Wi-Fi, audio, webcam, suspend, and external displays before returning to normal work.
Steps and verificationSince v4.0.3, Install → AI can install Hermes and OpenClaw. Complete the tool's onboarding and choose its entry in the default-agent settings. Start with a read-only task in a test repository, confirm the working directory, and review git diff. Opening the desktop app does not establish that authentication, model selection, subscriptions, or a background gateway are ready.
Steps and verificationInstall the Tailscale service, open its bar panel, select a device in the same tailnet, and press s to send files through Taildrop. Use c to copy its IP, n for its name, and d for its full DNS name. The terminal entry is omarchy tailscale send. Confirm receipt on the destination: an online device indicator does not prove a completed transfer.
Steps and verificationIdentify widget IDs with omarchy plugin list, move the bar with omarchy bar position bottom, and set a clock format with omarchy bar set omarchy.clock format "HH:mm". Media and microphone widgets may be disabled by default. Back up shell.json before changes and test one widget at a time. Keep customization in user configuration rather than editing package-owned plugin files.
Steps and verificationUse omarchy plugin update for Git-managed plugins and read the proposed diff before applying changes. The official tool accepts fast-forward updates and refuses conflicting local modifications. Preserve and review those edits instead of forcing a reset. Clone an internal widget with omarchy plugin clone omarchy.clock to keep your user plugin separate from the system package's implementation.
Steps and verificationBefore updating, check the Limine snapshot entry and verify an independent /home backup. A system snapshot restores system state; a personal backup restores work files. After reboot, check network access, input, sound, browser sessions, and a real project. Record versions and journal output when something regresses, then follow the recovery guide before choosing a rollback.
Steps and verificationPages map to real search intent, so you do not have to scan one oversized manual.
Hardware checks, ISO setup, disk risk, dual boot, and post-install verification.
Use the Super key to control windows, workspaces, and application launching.
Themes, monitors, input devices, and common customization paths.
Safe updates, snapshots, logs, and a recoverable diagnostic order.
Installation is not the finish line. A safer path validates your needs first, then covers installation, migration, updates, and recovery.
Begin with the relationship between Omarchy, Arch Linux, Hyprland, and Quickshell. Decide whether you want tiling, keyboard-first control, and rolling updates. List the software, corporate VPN, meeting tools, file formats, games, and peripherals you use every day. Anything without a proven replacement should be tested before a real disk changes.
Read the guideDownload the ISO only from an official channel and verify its version and SHA-256 against the release page. Back up important files independently, create recovery media, and confirm the target disk, encryption, and boot mode. Use a VM or spare device for exploration. For dual boot, address BitLocker, free space, and boot recovery first.
Read the guideDo not begin by replacing the entire configuration with somebody else's files. Learn high-frequency actions first: launch an app, move a window, change workspace, use fullscreen, capture the screen, and close a window. Map familiar Windows or macOS actions gradually, and use the built-in shortcut help for your installed version instead of an old social screenshot.
Read the guideAn Arch-based rolling system keeps changing. Save work, read prompts, and verify backups before an update; afterward, test networking, displays, audio, and critical apps. A system snapshot can restore system state but is not an independent backup of personal data. When something fails, record the version, time, and complete error before changing more variables.
Read the guideCurrent guides for Quattro, plugins, community tools, virtual machines, and distro comparisons.
Understand Quickshell, plugins, the ISO, and safe upgrades.
Install, update, and remove plugins while managing code risk.
Browse real projects with repositories, licenses, verification status, and X sources.
Compare VirtualBox, VMware, Parallels, and the Windows VM.
Compare desktop models, updates, and real workloads.
Choosing an operating system is not a contest between slogans. It is a test of whether the system can complete your real work, and different users should verify different things.
If your day revolves around editors, terminals, browsers, containers, and several parallel projects, tiled windows and workspaces can reduce repeated window hunting. You still need to validate Docker, GPU support, language toolchains, SSH keys, password management, and corporate networking. The apps, terminal, editor, and AI agent guides provide a practical post-install checklist.
Open the relevant guideMigration is rarely about finding a similar icon. The harder work is mapping keys, windows, file paths, application installation, and account licensing. The Windows/macOS comparison keeps familiar actions visible while you learn Super and workspaces. It also prompts you to verify Office files, creative tools, games, peripheral drivers, cloud storage, and collaboration services.
Open the relevant guideA beginner can use Omarchy, but should be willing to learn logs, backups, and basic terminal operations. If you prefer a conventional desktop, a long-term support track, or extensive vendor guidance, compare CachyOS and Ubuntu first. The useful comparison is a controlled task test on your hardware, not an unsupported claim that one distribution is universally faster or lighter.
Open the relevant guideTest real work before partitioning or replacing an operating system. Early evidence reveals incompatibility without turning a desktop experiment into unnecessary data risk.
Record the computer model, CPU architecture, GPU, Wi-Fi, Bluetooth, audio, fingerprint reader, displays, and docks. Know where virtualization, Secure Boot, and boot mode live in firmware, and keep a reliable path into firmware and recovery. A VM tests the installer and interface; graphics acceleration, sleep, battery life, external displays, and special keys require physical hardware.
Do not stop after finding an application with a familiar name. Open, edit, export, synchronize, and deliver a real file, then inspect fonts, macros, plugins, color, codecs, and collaboration comments. Developers should test Git, SSH, containers, databases, language versions, and local services. Gamers need evidence for anti-cheat, controllers, graphics drivers, and account restrictions.
Test your password manager, multi-factor authentication, security keys, corporate VPN, proxy, certificates, meeting camera, and screen sharing. Managed devices may have endpoint, encryption, or compliance requirements; successful Linux boot does not prove permission to access work resources. Keep another trusted device able to sign in and receive recovery codes during migration.
Store backups on an independent device or trusted cloud service and restore sample files before installation. System snapshots, configuration repositories, personal data, and a dual-boot loader are separate recovery problems. Estimate the time required to reinstall, recover accounts, download software, and rebuild the environment. If a lost workday is unacceptable, rehearse the full process on spare hardware first.
Keep what you know from Windows or macOS, then move into a keyboard-driven workflow at your own pace.
Open the migration guideThis site separates high-risk installation work, everyday productivity, and long-term maintenance. Enter through the problem you have now or follow the recommended sequence.
A complete Omarchy tutorial should do more than provide commands to paste. It should explain what a command changes, how to verify success, how to stop safely, and which results depend on hardware or the current release. This guide keeps official tool links, version dates, external dependencies, and risk notes near the relevant action. Long pages use descriptive headings and related links so readers can move between a quick answer and the deeper procedure.
Use the homepage as a topic map. During evaluation, read system requirements and distribution comparisons. During installation, use the ISO, virtual machine, dual-boot, and advanced-install pages. For daily work, move into shortcuts, themes, screenshots, input methods, displays, networking, and software. For maintenance, use updates, snapshots, and troubleshooting. Quattro and Plugins have dedicated pages because the new shell architecture changes both capability and security boundaries.
This is an independent guide and does not represent Omarchy, DHH, Basecamp, or 37signals. For releases, ISOs, checksums, upgrade entries, and plugin interfaces, it prioritizes the official Omarchy website, manual, and GitHub Releases. Arch, Hyprland, and other tools link to their own official documentation where possible. An external link lets you verify a source; it is not a security endorsement of third-party software.
Pages carry update dates, and changeable menu labels or commands are written in version context. The goal is not to promise identical results on every computer. It is to show how to obtain evidence: inspect hardware, preserve logs, compare configuration differences, verify backups, and prepare a rollback. If a page no longer matches a release, the contact page provides a route to report the version, source, and reproducible steps.
A successful Omarchy migration is not merely a desktop that reaches first boot. After a week, real files should still be deliverable, identity and networking should remain available, shortcuts should support rather than interrupt work, and critical functions should survive an update. When configuration fails, you should know where to read logs, restore a backup, or reverse the change. New content follows those observable outcomes instead of creating repetitive thin pages for extra keywords, while keeping facts, links, dates, and risk notes aligned across languages.
These answers help you choose a direction quickly. Follow the linked guide before changing disks, versions, or system configuration.
It is built on Arch Linux and provides an installer, a Hyprland/Quickshell desktop, default applications, themes, shortcuts, and maintenance tools. In daily use it feels like a complete, opinionated system rather than a loose dotfiles collection. Packages and lower-level changes still remain closely connected to Arch, so updates and troubleshooting may require both Omarchy and upstream documentation.
Read the full explanationYou can learn it, but your first experiment should not erase the only production system you own. Complete an install, network setup, update, and recovery exercise in a VM, on a spare computer, or on a separate drive. Beginners who can read complete errors, maintain data backups, and accept a tiled keyboard workflow usually adapt more safely.
Read the full explanationVirtual machines and dual boot are possible paths, but they answer different questions. A VM is lower risk and good for learning the interface, yet it cannot prove native graphics, sleep, or battery behavior. Dual boot uses real hardware but introduces partition, BitLocker, boot-entry, and recovery concerns. Apple Silicon also adds ARM versus x86_64 architecture constraints.
Read the full explanationQuattro 4.0 introduced Quickshell, a plugin architecture, packaged internals, and new configuration paths, so it is a substantial migration. A test machine can move earlier. A production workstation should first record custom configuration, verify an independent backup, and reserve recovery time. Always confirm the upgrade entry, ISO, and checksum on the current official release page.
Read the full explanationInstallability is not proof of safety. The official manual describes third-party shell plugins as unsandboxed code running with your user permissions inside the long-lived shell process. Review the author, repository, license, code, and update diff before enabling one. Test uncertain plugins away from production, and disable a suspect plugin while preserving logs before deleting configuration.
Read the full explanation