# What Omarchy Actually Is > What Omarchy really is (Arch Linux plus Hyprland plus Quickshell, assembled by someone with taste), how it differs from Windows, macOS, and Ubuntu, who it suits and who it does not, and how to try it without risking your current computer. --- # What Omarchy Actually Is Someone told you to look at Omarchy, or you saw a screenshot of a gorgeous desktop with no dock, no icons, and windows tiled edge to edge. Then you read "Arch, Hyprland, Quickshell" and every word was new. Before you wipe a drive, you want one thing: a clear picture of what this is and whether it is for you. This guide gives you that picture. It names the layers, explains the four ways Omarchy will feel different from what you know, and helps you decide, with a safe way to try it. Checked against Omarchy 4.0.4. ## Prerequisite None. If the word "Linux" itself still feels fuzzy, [Linux From Zero](/guides/linux-from-zero) is a gentle companion, but you can start here without it. ## How to read this - **Deciding whether to install?** Read [Phase 3](03-is-it-for-you-and-how-to-try-it.md) first, then come back for the why. - **Want it to finally make sense?** Read in order - each phase builds on the last. ## The phases 1. **[Distro, Desktop, Window Manager: The Layers](01-the-layers.md)** - what each name in "Arch + Hyprland + Quickshell" does, and what "omakase" means. 2. **[The Four Big Shifts](02-the-four-big-shifts.md)** - keyboard-first, tiling windows, configuration as text files, and a rolling release. 3. **[Is It for You, and How to Try It](03-is-it-for-you-and-how-to-try-it.md)** - who Omarchy suits, who it does not, and low-risk ways to find out. Next in this category: [Installing Omarchy](/guides/installing-omarchy) walks through the install, and [Omarchy for Windows, macOS, and Ubuntu Users](/guides/omarchy-for-windows-macos-and-ubuntu-users) translates your old habits. --- # Distro, Desktop, Window Manager: The Layers The official one-line description of Omarchy names an "omakase" Linux distribution built on Arch, the Hyprland window manager, and Quickshell. That is a wall of unfamiliar nouns. Each noun is one layer of a stack, and once you can name the layers, the rest of Omarchy stops feeling like magic. ## A computer is a stack of layers On Windows and macOS you never see the layers, because one company ships all of them as a single product. On Linux the layers are separate pieces, and different projects supply each one. Three words matter here. - **Distribution (distro).** The Linux kernel (the core that talks to your hardware) plus a curated collection of software, a package manager that installs and updates it, and an installer. Ubuntu, Fedora, and Arch are distros. - **Desktop environment (DE).** A complete, ready-made desktop: panels, settings app, file manager, window handling, and a consistent look. GNOME and KDE Plasma are the famous ones. Ubuntu's default desktop is a DE. - **Window manager (WM).** One narrower job: decide where each window goes on screen, how it is moved, and what the hotkeys do. A **tiling** window manager arranges windows in non-overlapping tiles for you. A DE usually includes a window manager as one of its parts. Omarchy takes the other route: it skips the bundled DE and builds a desktop from separate parts. > 📝 **Terminology.** On modern Linux the program that draws windows and decides where they sit is called a compositor. Hyprland is one. For this guide, read "Hyprland" as "the window manager": it is the layer that places windows and reacts to your hotkeys. ## The stack Omarchy assembles ```mermaid flowchart TD A["Your apps: terminal, browser, editor"] --> B["Omarchy shell on Quickshell: bar, menu, notifications, lock screen"] B --> C["Hyprland: window placement and hotkeys"] C --> D["Arch Linux: kernel, packages, updates"] ``` Read it bottom to top as "sits on": - **Arch Linux** is the foundation: the kernel, the package manager (`pacman`), and the huge catalog of software. Arch is known for being a **rolling release**, which Phase 2 explains. - **Hyprland** sits on top and runs the screen. It tiles your windows and listens for hotkeys. - **Quickshell** is, in the manual's words, a desktop construction kit: tools for building the visible parts of a desktop. Omarchy 4 uses it to build one long-running program, the **Omarchy shell**, which provides the top bar, the menu and app launcher, notifications, on-screen volume and brightness indicators, control panels, the lock screen, and the pop-up that asks for your password when a program needs admin rights. - **Your apps** run on top: a terminal, Chromium, Neovim, and the rest. Earlier versions of Omarchy used a separate program for each of those shell jobs (Waybar for the bar, Walker for the launcher, and so on). Version 4, nicknamed Quattro, replaced them all with the single Omarchy shell. Old screenshots and tutorials may show the earlier arrangement, so check the version before you trust one. ## What "omakase" means Omakase is the sushi-counter phrase for "I leave it up to you": you do not read a menu, you trust the chef. Applied to a computer, it means someone with strong taste has already chosen the editor, the browser, the theme, the fonts, the hotkeys, and how they fit together, so you start from a working, coherent system instead of assembling one from parts. Contrast that with vanilla Arch, where you install everything yourself, and with Ubuntu, where the choices are made for a very broad audience. Omarchy's choices are deliberately opinionated: Neovim, a terminal-heavy workflow, tiling windows, and a consistent theme across the whole desktop. The manual is clear that this is not an attempt to feel like Windows or macOS. It tells you to embrace the Linux side: some config files to edit by hand, and a lot of terminal. ## Who makes it Omarchy is created by DHH (David Heinemeier Hansson), and its source lives in the `basecamp` organization on GitHub. The README calls it a modern, opinionated Linux distribution. The manual is written in his voice, which is why it has opinions. Because Omarchy is Arch with a layer of choices on top, nearly everything you learn about the pieces (Hyprland, the terminal, `pacman`) is real, portable Linux knowledge. You are not locked into an Omarchy-only dialect. ## Where the manual lives The official manual is at [omarchy.org/manual](https://omarchy.org/manual/). When this guide says "the manual," that is the one. It changes fast, and Omarchy 4 changed a lot, so for anything version-specific, prefer the manual over blog posts written for earlier versions. Check yourself before moving on: ```quiz [ { "q": "Which layer of Omarchy decides where your windows sit on screen and reacts to hotkeys?", "choices": ["Arch Linux", "Hyprland", "Chromium"], "answer": 1, "explain": "Hyprland is the tiling window manager. Arch is the foundation underneath it, and Chromium is an app running on top.", "why": ["Arch supplies the kernel, the package manager, and the software catalog, not window placement.", null, "Chromium is an application that runs inside a window. It does not manage windows."] }, { "q": "What does it mean that Omarchy is an \"omakase\" distribution?", "choices": ["It only runs on one brand of hardware", "Someone has already made the many choices for you (apps, theme, hotkeys) so you start from a coherent system", "It has no package manager"], "answer": 1, "explain": "Omakase means leaving the choices to the chef. Omarchy ships an opinionated, pre-assembled setup rather than a blank slate." }, { "q": "What did Omarchy 4 (Quattro) do to the bar, launcher, notifications, and lock screen?", "choices": ["Moved each into its own separate program", "Replaced the separate programs with one long-running shell built on Quickshell", "Removed them entirely"], "answer": 1, "explain": "Version 4 rewrote the desktop shell in Quickshell, so the bar, menu, notifications, and lock screen live in one process." } ] ``` ## Recap 1. A distro is a kernel plus software, a package manager, and an installer. A desktop environment is a bundled desktop. A window manager only places windows. 2. Omarchy assembles its desktop from parts: Arch Linux, Hyprland, and an Omarchy shell built with Quickshell. 3. "Omakase" means the choices are already made for you, on purpose, by one person with strong opinions. 4. Because the pieces are real Linux tools, what you learn carries over beyond Omarchy. Next up, [The Four Big Shifts](02-the-four-big-shifts.md): how that stack changes the way you use a computer day to day. --- # The Four Big Shifts Most of the disorientation on day one comes from four habits you have to unlearn. They all trace back to the design from Phase 1: Omarchy is built from parts and tuned for a keyboard. Name them now and nothing later will blindside you. ## Shift 1: the keyboard drives The center of everything is the `Super` key. On a PC keyboard that is the Windows key. On a Mac keyboard, Linux treats the Command key as Super, so it sits exactly where Cmd always was, and Omarchy does not remap anything. There is no dock and no desktop icons. You start things with hotkeys or the menu: | You want | You press | |---|---| | The Omarchy menu (apps, settings, installing software) | `Super + Space` | | A terminal | `Super + Return` | | A browser | `Super + Shift + Return` | | A list of every mapped hotkey | `Super + K` | | Close the active window | `Super + W` | The manual says that when the system first starts you cannot do much with the mouse alone, and that `Super + Space` is the door in. The menu is not meant to be the main way to work, though. Frequent apps get their own hotkeys so you skip it. You do not have to memorize the list. The manual's advice is to skim the hotkeys chapter once and press `Super + K` whenever a binding slips your mind. ## Shift 2: windows tile themselves On Windows and macOS you drag windows around and stack them. In Omarchy you open a window and it takes the whole screen. Open a second and the two share the screen. Windows do not overlap, so you never dig one out from under another. The default arrangement is called dwindle. Each new window splits the space, and every window on the workspace stays visible. Try this on a live system: press `Super + Return`, then `Super + Shift + Return`. You get a terminal and a browser side by side. Press `Super + J` to stack them top and bottom instead, and `Super + J` again to put them back. Workspaces are like macOS Spaces or Windows virtual desktops, but fast: `Super + 1` jumps to workspace 1, and `Super + Shift + 1` sends the active window there. When a window really needs to float, `Super + T` toggles it out of the tiling and back. The manual's advice is to give tiling a fair chance first. > ⚠️ **Gotcha.** `Super + W` closes the window, and closing a window quits the app. There is no macOS-style limbo where an app keeps running with no windows. The [tiling guide](/guides/omarchy-tiling-windows-and-workspaces) goes deep on this. ## Shift 3: settings are text files Instead of a Settings app with hundreds of toggles, Omarchy keeps its configuration in plain text files under `~/.config`. The `~` means your home folder, and a folder starting with a dot is hidden by default. Those files are yours. | File | Controls | |---|---| | `~/.config/hypr/bindings.lua` | Your own hotkeys and overrides of the defaults | | `~/.config/hypr/monitors.lua` | Monitors, resolution, and scaling | | `~/.config/hypr/input.lua` | Keyboard layout, mouse, and trackpad | | `~/.config/hypr/looknfeel.lua` | Gaps, borders, animations | | `~/.config/omarchy/shell.json` | The top bar, plus idle and lock timings | You do not need to hunt for these. The menu's _Setup_ entries (Keybindings, Monitors, Input, and more) open the right file in your editor and restart whatever needs it when you close the editor. The default editor is Neovim, so you save and quit with `:wq`. If you have never used a terminal editor, [Editing in the Terminal](/guides/editing-in-the-terminal) covers survival. Omarchy 4 uses Lua for Hyprland's config. Here is the manual's own example of swapping one app's hotkey, which shows the shape of it: ```lua hl.unbind("SUPER + SHIFT + O") o.bind("SUPER + SHIFT + O", "Joplin", "joplin-desktop") ``` The first line removes the default binding for `Super + Shift + O` (which opens Obsidian), and the second binds the same keys to a different app. Older tutorials show config files with a `.conf` ending and a different syntax. Those belong to Omarchy 3 and earlier, so skip them. Why files instead of panels? Every tweak is visible, copyable to your next machine, and simple to put in version control. If you make a mess, _Update > Config_ in the menu restores individual config files to their shipped defaults. The files in `/usr/share/omarchy` belong to Omarchy itself. Do not edit them: an update overwrites them. Override values in `~/.config` instead. ## Shift 4: a rolling release with one update button Windows and macOS have versions: you live on one, then upgrade to the next. Ubuntu has releases too. Arch is a **rolling release**: there is no "next version" to upgrade to. Packages flow in continuously, so you stay current by updating regularly. Omarchy wraps that in one command. _Update > Omarchy_ in the menu (or `omarchy update` in a terminal) updates Omarchy and every package on the system, and it takes a snapshot first. A small circle-arrow icon appears next to the clock in the top bar when an update is waiting. Omarchy even stops you from running a bare `pacman -Syu`, because you would skip the snapshot and the configuration updates. The snapshot is your safety net. If an update goes wrong, you can pick the earlier snapshot from the boot menu and restore it (the [recovery guide](/guides/when-omarchy-breaks) covers it). New installs follow the `stable` channel, which tracks official releases and an Arch mirror that runs about a month behind. The trade-off is real. You get fresh software and security fixes quickly, but things change under you, and Omarchy 4 changed a lot. That is why this series states the version it was checked against. ## Your turn: predict the hotkey You have met two hotkeys that open things. Try recalling the one that shows all the rest. ```exercise [ { "type": "predict", "task": "Which hotkey shows every mapped hotkey? Write it the way this guide does, for example `Super + Space`.", "accept": ["Super + K", "/^super\\s*\\+\\s*k$/i"], "hint": "It is the only hotkey the manual says you actually have to memorize." } ] ``` Check yourself before moving on: ```quiz [ { "q": "Where do Omarchy's settings mostly live?", "choices": ["In a single graphical Settings app", "In plain text files under ~/.config that the Setup menu opens for you", "Inside /usr/share/omarchy, which you are expected to edit"], "answer": 1, "explain": "Your files live under ~/.config. The /usr/share/omarchy files belong to Omarchy and are overwritten on update.", "why": ["Omarchy deliberately has no single settings app. The Setup menu opens the right file instead.", null, "Files in /usr/share/omarchy are replaced by updates, so changes there are lost. Override in ~/.config instead."] }, { "q": "You open a terminal, then a browser. What do you see?", "choices": ["Two overlapping windows you must arrange", "The two windows tiled next to each other, sharing the screen", "Only the browser, with the terminal hidden"], "answer": 1, "explain": "A tiling window manager places windows for you so they share the screen without overlapping." }, { "q": "What does \"rolling release\" mean for how you update?", "choices": ["You wait for a new numbered version and then upgrade", "Updates arrive continuously, so you stay current by updating regularly", "The system never updates"], "answer": 1, "explain": "Arch has no big version jumps. Omarchy gives you one command, with a snapshot taken first, to keep everything current." } ] ``` ## Recap 1. `Super` is the center of the keyboard-driven desktop: `Super + Space` for the menu, `Super + K` for the hotkey list. 2. Windows tile themselves, workspaces replace window-dragging, and `Super + T` floats a window when you must. 3. Configuration is text under `~/.config`, opened for you by the _Setup_ menu. Never edit `/usr/share/omarchy`. 4. Arch is a rolling release. Omarchy updates everything with one command and takes a snapshot first. Next up, [Is It for You, and How to Try It](03-is-it-for-you-and-how-to-try-it.md): a plain look at who this suits and how to test it safely. --- # Is It for You, and How to Try It Omarchy is a strong opinion packaged as an operating system. Opinions fit some people perfectly and grate on others. This phase gives you a straight list of who tends to love it, who tends to bounce off, and how to find out with little risk. ## Who it suits Omarchy tends to fit you if most of these are true: - You live in a terminal, a code editor, and a browser, and you like keyboards. - You enjoy a consistent, themed desktop that someone tuned for you, and you are happy to change what you do not like. - You are willing to spend a couple of weeks building new muscle memory. The manual itself says to give it two weeks. - You like being able to see and copy your settings, because they are text files. Developers are the obvious audience: the base install ships Neovim, tmux, Lazygit, and a language-version manager called Mise, and the menu installs a long list of development environments. But the manual also bundles LibreOffice, Obsidian, an OBS Studio video recorder, and the Kdenlive video editor, so it is not only for programmers. ## Who it probably does not suit Be wary if any of these describe you: - **You need a specific app that has no Linux version.** Check this before anything else (more below). - **You want to click through a settings app for everything.** Omarchy edits files, and the manual says plainly that it is not trying to be Windows or macOS. - **You cannot afford a bad afternoon.** Omarchy is a rolling release. It protects you with snapshots, but updates can still break things, and fixing them means reading and typing. - **You need a guarantee your exact hardware works.** Nobody can promise that, as the next section explains. None of this is a defect. It is the shape of the product. Knowing it beforehand is the whole point. ## Three questions, answered straight ### Will it run on my hardware? The manual does not publish minimum requirements, so this guide will not invent numbers. The Omarchy homepage claims it runs on a very wide range of machines, including a 2011 ThinkPad with 2 GB of RAM. Treat that as marketing, not a promise. What the manual does say about hardware: - **Intel Macs** are supported, but only as the sole operating system on the machine, and some models have known problems. Machines with the first-generation Touch Bar chip (T1) have a non-working Touch Bar and no sound. Models with the T2 chip get patched drivers. - **M-series (Apple silicon) Macs** are not directly supported. A community guide exists for Apple M1 and M2, and it takes real effort. - **Displays:** Omarchy assumes a high-resolution (2x) screen by default. On an ordinary 1080p screen, apps can look oversized until you change one scaling setting. It is a known, documented fix, covered in the [install guide](/guides/installing-omarchy). Anything else (a specific Wi-Fi chip, fingerprint reader, or webcam) you can only learn by trying it, or by asking in the `#omarchy-help` channel on the community Discord at [omarchy.org/discord](https://omarchy.org/discord). ### Will my apps run? Sort what you rely on into three bins: 1. **Already there, or one menu entry away.** A browser (Chromium by default, with Chrome, Firefox, Brave, and others installable), office tools (LibreOffice), notes, password managers, Spotify, Steam, and many web apps. Anything that works in a browser works here. 2. **Needs a Windows or Mac program you cannot replace.** Omarchy offers a Windows 11 virtual machine you install from the menu. The manual calls it a good way to run Microsoft Office. It has no GPU passthrough, so it is not suitable for gaming or video editing, and you need your own license key for the gated features. 3. **Games.** The manual says Valve's Proton compatibility layer makes tens of thousands of Windows games playable on Linux. Games that depend on anti-cheat can fail: the manual notes there is no Fortnite or Rocket League through the Epic launcher, and suggests cloud gaming (Xbox Cloud Gaming, GeForce NOW) for such titles. For any professional tool not named here, do the check you would do for any move to Linux: look for a native Linux version, a web version, or a good alternative, before you commit. ### How steep is the learning curve? Expect it to be steeper than Ubuntu and gentler than assembling Arch yourself (a judgement call, not a measurement). You will spend the first days asking "how do I do X" and the answer is usually a hotkey, a menu entry, or a line in a file. The upside is that the answers are consistent, because one person designed the whole system. > 💡 **Key point.** The three questions above are checkable before you install anything. An hour of checking costs far less than a wiped drive. ## How to try it with the least risk Pick the lowest-risk option that is realistic for you. 1. **A spare computer.** The safest choice. An old laptop or desktop you can wipe means nothing of yours is at stake, and it tests real hardware. 2. **A virtual machine.** A VM runs Omarchy inside a window on your current computer. The manual links user-written guides for VirtualBox (with a warning that performance probably will not be great), VMware Workstation on Windows 11, and Parallels. You see the look and the hotkeys, but you will not learn how your real Wi-Fi, trackpad, or sleep behaves. 3. **Dual boot.** Omarchy has a free-space install: you shrink your Windows partition and install Omarchy alongside it, so Windows stays. It tests real hardware with a way back, but it changes your partitions, so you must back up first. It also requires turning off BitLocker in Windows. The [install guide](/guides/installing-omarchy) walks through it. Whichever you choose, back up anything you care about first. The full-disk install wipes the drive you select. Not sure about the underlying ideas? [Linux From Zero](/guides/linux-from-zero) and [The Terminal & Shell, Explained](/guides/the-terminal-and-shell) fill in the background and make the first week gentler. ## Your turn: build your own go or no-go list Write down what you actually do on a normal week and test it against Omarchy before you install. ```exercise [ { "type": "task", "task": "List the 5 apps or tasks you cannot live without. For each one, find out whether it has a Linux version, a browser version, or a good alternative, or whether it would need the Windows VM. Then decide: go, no-go, or try on a spare machine first.", "reveal": "A good result is a short table: app, how it would run on Omarchy (native, web, alternative, VM), and a verdict. If one must-have app has none of those, that is a no-go until you find a way, and you have lost nothing but an hour.", "checklist": ["I listed at least 5 apps or tasks", "I checked each one against the Linux, browser, alternative, or VM options", "I noted which hardware (Wi-Fi, trackpad, display) I have not verified", "I chose a low-risk way to try it"] } ] ``` Check yourself before moving on: ```quiz [ { "q": "You need Microsoft Office for work and have no Linux alternative you like. What does Omarchy offer?", "choices": ["Nothing, Office cannot run at all", "A Windows 11 virtual machine you install from the menu, which the manual recommends for Office but not for gaming or video editing", "A built-in Office clone that opens every file perfectly"], "answer": 1, "explain": "The Windows VM runs Windows 11 Pro (unactivated) in Docker. It has no GPU passthrough, so it suits Office-style apps, not games or video editing.", "why": ["The VM is the manual's stated route for programs you cannot do without.", null, "Omarchy ships LibreOffice, which is a separate project and may not match Office on every file."] }, { "q": "Which statement about hardware matches what the manual says?", "choices": ["Omarchy lists exact minimum RAM and CPU requirements", "Intel Macs are supported as the only OS, while M-series Macs are not directly supported", "Every laptop's Wi-Fi works out of the box"], "answer": 1, "explain": "The manual gives no minimum specs. It supports Intel Macs (as the only OS) and says M-series Macs are not directly supported." }, { "q": "Which trial option changes your disk's partitions on a real machine, and so needs a backup and BitLocker turned off?", "choices": ["A virtual machine", "Dual boot with a free-space install", "Reading the manual"], "answer": 1, "explain": "Dual boot shrinks your Windows volume to make room. A VM lives inside a file and leaves your partitions alone." } ] ``` ## Recap 1. Omarchy suits keyboard-comfortable people who want a tuned, consistent system and will invest a couple of weeks. It suits poorly if you need non-Linux-only apps, want a clickable settings app, or cannot risk downtime. 2. There are no published minimum requirements. Intel Macs work with caveats, M-series Macs are not directly supported, and 1080p screens need a scaling tweak. 3. Check your must-have apps first: native, browser, alternative, or the Windows VM. 4. Try it on a spare machine, in a VM, or by dual booting, and back up first. Next up: [Installing Omarchy](/guides/installing-omarchy), a step-by-step walk through the whole process. After that, [Omarchy for Windows, macOS, and Ubuntu Users](/guides/omarchy-for-windows-macos-and-ubuntu-users) maps your old habits onto the new ones.