How to Customize Omarchy Without Breaking Future Updates

The most useful Omarchy customization rule is simple:

Put your changes in ~/.config. Do not edit package-managed files under /usr/share/omarchy for ordinary customization.

The current Omarchy manual treats those two locations as an ownership boundary. Files in ~/.config are yours. Files in /usr/share/omarchy belong to Omarchy and can be replaced by package updates.

Use the Setup menu when it already exposes the setting

Omarchy provides direct menu entries for common configuration jobs, including:

• monitors;
• keybindings;
• input devices;
• default applications;
• configuration files.

Using those entry points has one advantage beyond convenience: Omarchy can restart the relevant process after you save the file.

That is safer than randomly hunting through packaged files and guessing what needs to be reloaded.

Override defaults instead of editing them in place

Hyprland-related user configuration lives under ~/.config/hypr.

Current examples include:

• bindings.lua for keybindings;
• monitors.lua for displays and positions;
• input.lua for keyboard, mouse and trackpad behavior;
• looknfeel.lua for gaps, borders and visual behavior;
• autostart.lua for session startup commands.

The main configuration loads Omarchy defaults and then your overrides.

That arrangement is what lets Omarchy update its own configuration while keeping your changes separate.

Keep shell changes in your own shell file

For aliases, functions and environment exports, the manual says to use your own ~/.bashrc.

That file is not supposed to be overwritten by normal Omarchy updates.

The same principle applies more broadly: prefer user-owned extension points over edits to package-owned internals.

What happens when an update must refresh a config?

Omarchy's current Common Tweaks documentation warns that some updates may occasionally need to restore a configuration file to its new default.

When that happens, displaced changes are preserved in a .bak file in the same directory.

That does not mean every arbitrary customization is guaranteed to work forever. It means the update path tries to avoid silently destroying the previous version.

After a major configuration migration, compare the new file with the backup rather than blindly copying the entire old file back over the new format.

Recover one broken config before resetting everything

If a customization breaks part of the desktop, start small.

The current menu provides Update > Config for restoring individual packaged configurations.

For a broader reset, current Omarchy documentation provides:

omarchy reinstall configs

A full reinstall path exists too, but resetting one configuration is usually less disruptive than resetting the entire environment.

Back up personal dotfiles

Once your setup matters to you, treat the configuration like source code.

A simple backup or Git repository for selected dotfiles can preserve:

• keybindings;
• monitor layouts;
• shell aliases;
• input settings;
• autostart entries;
• personal Omarchy extensions.

Do not blindly publish secrets, tokens or private configuration just because the surrounding dotfiles belong in Git.

Themes have their own user directory

Custom themes are another example of the same ownership model.

They belong under ~/.config/omarchy/themes, not inside the packaged theme directory.

See How to Create and Install Custom Omarchy Themes for that workflow.

For terminal-based control and discovery, see The Omarchy CLI.

The durable mental model is more valuable than any individual tweak: customize through user-owned override points and let Omarchy keep ownership of its packaged defaults.