Omarchy Configuration: Keep Personal Overrides Separate from Managed Defaults
Understand Omarchy's user dotfiles, package-owned defaults, themes, and hooks so customizations survive updates without widening execution trust.
Omarchy is an Arch-based desktop distribution organized around Hyprland, Quickshell, and a curated set of applications and workflows. Its configuration model matters as much as its visual defaults: user-owned overrides live primarily under ~/.config, while /usr/share/omarchy contains files owned by the Omarchy package. Editing the latter directly may appear to work, but a package update can replace those changes.
The maintenance-safe pattern is to customize through the user layer, retain a recoverable copy of the configuration, and treat executable hooks and downloaded themes as code. This lets the distribution manage its defaults while making local behavior explicit.
Locate the supported customization surface
The Omarchy manual lists user configuration such as ~/.config/hypr/bindings.lua, monitors.lua, input.lua, and autostart.lua, plus ~/.config/omarchy/shell.json. The main Hyprland configuration loads defaults and the user’s override files. Use the Omarchy menu or the documented files for a change, then inspect the diff before logging out or upgrading.
For example, if a monitor arrangement is wrong, change the monitor-specific user file rather than patching an internal distribution default. Keep a note of why the override exists and which display model or resolution it addresses. A small, isolated file is easier to rebase mentally when upstream changes than a fork of the entire configuration tree.
Back up only the files you intend to keep. Dotfile repositories can accidentally publish tokens, private keys, browser state, SSH configuration, or machine-specific paths. Check ignored files and review git diff --cached before committing; do not blindly add the whole home directory. Include a restoration note that identifies the Omarchy release and the files the user layer expects.
Updates can change behavior, not just package versions
Omarchy’s updates may refresh package configuration and system defaults. Treat an update as a change to a managed workstation image: read the current update guidance, keep a snapshot or independent backup, and review the release notes before relying on a customization. Test major changes on a spare machine or VM where practical. If a default now provides a behavior that used to require an override, remove the obsolete local patch instead of letting two configuration layers compete.
The manual documents hooks for events including post-boot, post-update, and pre-refresh-pacman. They run scripts from user-controlled locations; this makes them powerful integration points and also code-execution surfaces. Read each sample and the current manual before enabling a hook, make it executable only when intended, and inspect all commands before installing it. A hook that runs after boot or update should be idempotent, bounded, observable, and safe if it runs again after partial failure. If it invokes sudo, account for the fact that the hook itself runs as the user and may require its own authorization.
An intentionally small hook might only emit a diagnostic marker:
#!/bin/sh
set -eu
logger -t omarchy-user-hook -- "post-boot customization reached"This example does not configure a service or alter system state; use the event name and installation procedure documented by the installed Omarchy version. Avoid downloading and immediately executing a remote script. If a hook must install packages or change system configuration, keep privileged steps explicit and reviewable, and make failure behavior clear.
Themes are not all inert data
The Omarchy theme documentation distinguishes color data and generated application settings from files that can execute code or alter application behavior. Its installation process intentionally filters certain file types from themes installed from external repositories. A locally authored theme has a different trust boundary because it is your own code. Review theme contents before use, especially compositor scripts, terminal startup settings, editor extension configuration, and executable hooks. A palette preview does not establish that the rest of a repository is safe.
Keep personal themes under the documented user directory and distribute them only after removing secrets, machine paths, and unreviewed executable configuration. Pinning a source repository to a reviewed commit is safer for repeatability than depending on a mutable branch, but a commit pin does not prove the code is trustworthy.
Validate customizations after a release change
Before updating, record the Omarchy and kernel versions and save the user configuration. Afterward, check that the compositor starts, expected keybindings work, monitor layout and input are correct, autostart applications have not multiplied, theme selection behaves as intended, and hooks have not emitted unexpected privileged prompts. Inspect logs before concluding that the desktop is healthy. Revert one override at a time if a regression appears; do not erase the full user configuration to fix one broken keybinding.
The resulting mental model is simple: package-owned defaults are upstream policy, ~/.config is the user customization layer, and hooks or third-party theme code are executable inputs. Keeping those boundaries separate is what makes a highly customized desktop maintainable across updates.
Related:
- XDG Base Directories: A Practical Contract for Linux User Data
- Understanding systemd: Units, Targets, and the Modern Linux Init System
Sources: