Keep personal configurations through Omarchy updates

An update finishes, but your shortcut no longer works or a window rule reports an error. Your file may still exist. The problem can be changed defaults, changed syntax, a migration, or a setting that another layer now overrides. Keeping a customization means preserving its intent and adapting it when necessary, not freezing every old file forever.

This guide concerns personal configuration. For a system that cannot boot, use update recovery and backups. A system snapshot and a backup of your personal files cover different failures.

1. Identify what owns the setting

Location	Ownership and behaviour	Maintenance approach
/usr/share/omarchy/	Package-managed defaults and tools	Do not keep personal edits here
~/.config/hypr/	Personal entry and overrides	Keep your intent, check API/syntax changes
~/.config/omarchy/shell.json	Personal shell behaviour and layout	Preserve unrelated keys when editing
~/.config/omarchy/shell.toml	Personal appearance above the theme	Check supported keys and precedence
~/.local/state/omarchy/current/theme/	Generated active theme	Change the theme source or template instead
Omarchy toggle state	Runtime/persistent modes	Record relevant toggles separately

The personal directory is the right place to customize, but it is not a promise that all old settings remain valid forever. Updating a compositor can change accepted syntax; a migration can adjust a file; a refreshed config can replace it. Meanwhile, generated theme files are rebuilt when the theme is applied.

2. Leave a useful checkpoint before an update

Record omarchy version, the current theme, relevant toggle states and the files you changed. For each customization, write a sentence about the desired behaviour: “Chat opens on workspace 3 without stealing focus” survives a syntax change better than an unexplained block of code.

For a file that exists:

cp -i ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.before-update

Use a fresh checkpoint name and copy the other files you actually changed. Include custom templates, hooks or plugin settings if your behaviour relies on them. Store an additional copy off the machine if you need protection against disk failure; a neighbour file is only a convenient local checkpoint.

If you want a meaningful three-way comparison later, also retain the shipped baseline used when making the customization. In a graphical session where OMARCHY_PATH is defined, the fresh-install binding template is at $OMARCHY_PATH/config/hypr/bindings.lua. That file can be mostly comments: inherited keybindings also live under default/hypr/, so preserving the personal template alone does not preserve all default behaviour.

3. Compare the failure before copying anything back

omarchy version
hyprctl configerrors
omarchy menu keybindings --print

Use commands available in your installed version. If only one shortcut fails, start with that file and loaded binding. If the shell alone is wrong, inspect its JSON/TOML or plugin state rather than changing Hyprland.

For the previous personal file and current one:

diff -u ~/.config/hypr/bindings.lua.before-update ~/.config/hypr/bindings.lua

Exit status 1 from diff means differences were found, not that the comparison failed. Removed lines begin with -, added lines with +; context lines show where they belong. Read the changes, including new imports and helper calls, before deciding which old lines to restore.

Comparison	Question it answers
Old personal file → current personal file	Was this file changed?
Old shipped baseline → new shipped baseline	What did the system change?
Desired behaviour → current observed behaviour	Does the customization still do its job?

If the baseline was not saved, you cannot reconstruct a reliable three-way merge from two files. Consult the release notes and matching source; do not assume every difference is an unwanted system edit.

4. Understand a targeted configuration refresh

The pinned omarchy-refresh-config accepts a path relative to ~/.config:

omarchy-refresh-config hypr/bindings.lua

This is a replacement operation, not a diagnostic query. Use it only when you intentionally want the new shipped personal template. It copies $OMARCHY_PATH/config/hypr/bindings.lua over the personal file and, when contents differ, keeps the old file as bindings.lua.bak.<timestamp>. Identical copies do not leave a redundant backup. A path absent from the shipped config tree is rejected.

A refresh does not promise to reload every affected application. After comparing and reintroducing your minimal changes, apply the file through its normal configuration menu and check the real behaviour.

Find candidate backups without modifying them:

find ~/.config/hypr -maxdepth 1 -type f -name 'bindings.lua.bak*' -print

Choose a backup based on its contents and context, not only the newest filename. Migrations can use other backup patterns or different logic; this timestamp pattern describes this helper, not every update step.

5. Migrate a small intent instead of copying an old desktop

Suppose an older personal binding uses .conf syntax, while the new entry loads Lua. Pasting the old block into bindings.lua will not preserve the shortcut. Identify its key, command and previous behaviour, then express that intent using the current helper:

o.rebind("SUPER + SHIFT + F", "Open Documents", {
  launch = 'nautilus "$HOME/Documents"',
})

This is an example only if that key and existing path suit your installation. Verify the command independently, save one change, then test the key. Continue with the next customization only after the first works. See the shortcut tutorial for the complete exercise.

Preserve new setup/import lines you understand to be required by the current entry. For window rules, recheck actual app identities and test a newly created window; for templates, switch a theme and inspect regenerated output. Correct syntax alone does not prove preserved behaviour.

6. Restore the smallest useful scope

Recovery	Suitable situation	What to consider
Undo one line	One new change caused a problem	Smallest impact
Restore one saved file	Its previous form is still compatible	Later edits to that file will be replaced
Refresh one shipped config	You intentionally want a new baseline	Reintroduce personal intent after comparison
Reset all configs	You intentionally abandon the personal setup	Broad overwrite, not an ordinary undo

Do not use omarchy reinstall configs as the routine last step of a tutorial. In the pinned implementation it copies the packaged /etc/skel tree over the home directory, including shipped dotfiles and other defaults, and runs additional refresh steps. It is broader than “repair this one binding,” and does not provide a complete backup of your previous setup.

After recovering one file, inspect errors, run the actual task, and check unrelated menu/terminal routes. If an update introduced an incompatible API, repeatedly restoring the same old file will reproduce the error.

7. Keep a maintenance record you can reuse

Keep the affected version, source link, changed file, desired behaviour, backup location and verification result together. When a workaround is no longer necessary, remove it after testing the supported path; accumulated overrides can hide improvements and make future diagnosis harder.

For reporting a remaining problem, provide the smallest relevant configuration excerpt and observed error using the support template. Remove secrets, private paths and unrelated logs before sharing.

Sources and related guides

Targeted refresh implementation · Full configuration reset · Update process · Official updates

Continue with configuration loading or backup and restoration.