Omarchy customization: build a desktop that fits your work
Choose the right configuration layer for themes, fonts, shortcuts, windows, default apps and startup, with a safe learning route.
Based on public documentation; not hardware-tested. Match the instructions to your version and hardware.
Good customization starts with a task: read code comfortably, reach a project faster, keep a call beside your notes, or find your windows after unplugging a monitor. Omarchy lets several components cooperate to support these tasks. Knowing which component controls the result prevents a small adjustment from turning into a replacement of the entire configuration.
This chapter organizes the customization guides by what you want to achieve. Start with the configuration model, choose one experiment, and keep its recovery instructions nearby. The official dotfiles guide describes upstream configuration ownership; our linked articles add worked examples and failure branches.
Before editing: identify the owner
Section titled “Before editing: identify the owner”| What you want to change | Responsible area | Start here |
|---|---|---|
| Desktop and supported application colors | Theme and application integration | Theme gallery and application theming |
| Bar content, spacing and size | Omarchy Shell | Bar customization |
| Window arrangement and matching rules | Hyprland | Layouts and window rules |
| A link, file or launch action | Defaults, associations and shortcuts | Default apps and Web Apps |
| Something running after login | Session startup or a user service | Autostart |
| Screen locking and idle behavior | Shell idle policy and power handling | Lock, screensaver and idle |
Several symptoms can share a visible result without sharing a cause. Small text might come from monitor scaling, a terminal font or the bar’s own size. “The browser is still wrong” might refer to a keybinding, a clicked URL or a Web App. Name the exact action before choosing the configuration file.
Readability and appearance
Section titled “Readability and appearance”Choose a theme in the preview gallery, then test it with your real work rather than only a wallpaper. Can you distinguish selected text, comments and errors? Are Chinese characters and icons readable? Does the application you spend most time in actually follow the palette?
- Fonts and text size separates font choice, missing glyphs and display scaling.
- Bar customization works through clock content, order, height and text size.
- Window appearance compares gaps, borders, transparency and animation using the same workspace.
- Application theming traces how a theme becomes an application setting and what to check when it does not.
Make a readability improvement before collecting cosmetic changes. Record the old value and compare the same window at the same scale. A theme change and a font change together make it harder to explain which one helped.
Window behavior and everyday actions
Section titled “Window behavior and everyday actions”| Goal | Guide | Practical experiment |
|---|---|---|
| Reach a frequent task faster | Personal keybindings | Add one action, inspect conflicts, then restore it |
| Keep a predictable arrangement | Window layouts | Compare tiling, scrolling, floating, groups and scratchpads |
| Treat one application differently | Window rules | Match a real window before changing its behavior |
| Keep work organized across screens | Workspaces | Move a window and a whole workspace separately |
| Open links and documents consistently | Default apps | Test URL, shortcut, PDF and Web App entry points |
Window rules determine how a matching window behaves; a layout determines how windows share space; a workspace groups work. Learn those boundaries before adding rules for every application. For monitor position and scaling, use the separate display guide.
Startup, idle and long-term maintenance
Section titled “Startup, idle and long-term maintenance”Use autostart and background tasks when you want an app at login or a service with a longer lifetime. The chapter asks who already starts the process, how to read its logs and how to undo the change. A duplicate launch can come from two startup owners, not a defective application.
Use lock and idle behavior for presentations, longer tasks and timeout changes. Keeping a screen visible, preventing sleep and requiring authentication are different goals; verify each separately.
Finally, use configuration maintenance after an update. Preserve the reason for your change as well as the file itself. An old file may still parse while bypassing a new default you intended to keep.
Three useful reading routes
Section titled “Three useful reading routes”- My first change: configuration loading → keybindings → maintenance. Finish with one shortcut you can add and remove confidently.
- A comfortable desktop: themes → fonts → window appearance → bar. Compare with the same document and applications.
- A repeatable workbench: layouts → workspaces → window rules → autostart. Check what survives login, monitor changes and updates.
A configuration experiment is finished when you can undo it
Section titled “A configuration experiment is finished when you can undo it”Write down the desired result, the owner, the changed file and the previous state. Change one thing, perform the real action and inspect the result. Restore both edited files and any separate menu toggles used during the experiment. See backups and recovery for the difference between personal configuration copies and system snapshots.
Some linked tutorials use Hyprland Lua in the pinned quattro snapshot, while older installations use .conf syntax and different desktop components. Read each article’s version note before copying an example. This topic page organizes the learning path; it does not make those examples compatible with every release.