Migrations and Update Pipeline

Omarchy’s Migrations and Update Pipeline ensure that changes to configuration, packages, and system defaults apply smoothly over time. When you run updates, Omarchy:

  • Fetches the latest installer code.
  • Executes any pending migrations.
  • Updates system and AUR packages.
  • Handles necessary restarts or relaunches (e.g., Hyprland, Waybar).

An Index for this section:

Update Pipeline Overview

Omarchy’s update pipeline coordinates code updates, migration scripts, package upgrades, and service restarts. It runs via the omarchy-update command:

#!/bin/bash
set -e
omarchy-snapshot create || [ $? -eq 127 ]
omarchy-update-git
omarchy-migrate
omarchy-update-system-pkgs
omarchy-update-restart
omarchy-restart-waybar

This workflow ensures each step completes before proceeding to the next, minimizing system drift and manual steps.

Migrations Mechanism

Migrations live in ~/.local/share/omarchy/migrations/*.sh. Each script:

  1. Echoes a description.
  2. Checks if it has run before (state tracked in ~/.local/state/omarchy/migrations).
  3. Executes shell commands.
  4. Marks itself as applied or skipped on success/failure.
#!/bin/bash
# bin/omarchy-migrate

STATE_DIR="$HOME/.local/state/omarchy/migrations"
mkdir -p "$STATE_DIR" "$STATE_DIR/skipped"

for file in ~/.local/share/omarchy/migrations/*.sh; do
  filename=$(basename "$file")
  if [[ ! -f "$STATE_DIR/$filename" && ! -f "$STATE_DIR/skipped/$filename" ]]; then
    echo -e "\e[32m\nRunning migration (${filename%.sh})\e[0m"
    if bash "$file"; then
      touch "$STATE_DIR/$filename"
    else
      if gum confirm "Migration ${filename%.sh} failed. Skip and continue?"; then
        touch "$STATE_DIR/skipped/$filename"
      else
        exit 1
      fi
    fi
  fi
done

Each migration runs exactly once per device, ensuring idempotent updates.

Representative Migrations

Below are key examples of migrations you may encounter. Each illustrates common patterns in Omarchy’s evolution.

Migration Script Purpose
UWSM env & Hyprland relaunch 1751134560.sh Add UWSM to PATH, prompt Hyprland relaunch.
Add Omarchy package repo 1751134561.sh Insert [omarchy] repo into /etc/pacman.conf.
Fix Waybar “update” key click 1754568612.sh Correct on-click path; restart Waybar.
Migrate Chromium launchers & Hyprland bindings 1755507891.sh Switch to omarchy-launch-webapp/browser helpers.
Various QoL fixes (icons, CSS, services, packages…) multiple scripts Small tweaks over time (e.g., xmlstarlet, MTU).

UWSM Environment & Hyprland Relaunch

This migration adds Omarchy’s binaries to the user’s PATH via UWSM and prompts for a Hyprland restart.

echo "Add UWSM env"
export OMARCHY_PATH="$HOME/.local/share/omarchy"
export PATH="$OMARCHY_PATH/bin:$PATH"
mkdir -p "$HOME/.config/uwsm/"
omarchy-refresh-config uwsm/env
echo -e "\n\e[31mOmarchy bins have been added to PATH…\e[0m"
mkdir -p ~/.local/state/omarchy/migrations
gum confirm "Ready to relaunch Hyprland?" && \
  touch ~/.local/state/omarchy/migrations/1751134560.sh && \
  uwsm stop

What it does:

  • Sets OMARCHY_PATH and updates PATH.
  • Copies UWSM config.
  • Prompts the user to restart Hyprland seamlessly.

Adding the Omarchy Package Repository

This script injects the Omarchy package repository into Pacman’s config and refreshes the database.

echo "Add Omarchy Package Repository"
omarchy-refresh-pacman-mirrorlist
if ! grep -q "omarchy" /etc/pacman.conf; then
  sudo sed -i '/^\[core\]/i [omarchy]\nSigLevel = Optional TrustAll\nServer = https://pkgs.omarchy.org/$arch\n' /etc/pacman.conf
  sudo systemctl restart systemd-timesyncd
  sudo pacman -Syu --noconfirm
fi

What it does:

  • Runs helper to refresh mirrorlist.
  • Inserts [omarchy] immediately after [core].
  • Performs a full system upgrade.

Fixing Waybar Config Keys

Certain Waybar updates change module definitions. This migration corrects the click path for the update icon and restarts Waybar.

echo "Update Waybar config to fix path issue with update-available icon click"
if grep -q "alacritty --class Omarchy --title Omarchy -e omarchy-update" ~/.config/waybar/config.jsonc; then
  sed -i 's|\("on-click": ".*\)omarchy-update"|\1omarchy-update"|' ~/.config/waybar/config.jsonc
  omarchy-restart-waybar
fi

What it does:

  • Searches for the old click handler.
  • Fixes JSON key quoting and reloads Waybar.

Migrating Chromium/Webapp Launchers & Hyprland Bindings

As Omarchy centralizes launcher logic, this migration replaces direct Chromium calls with the new helpers.

#!/bin/bash
echo "Migrating to use omarchy-launch-webapp and omarchy-launch-browser"
for desktop_file in ~/.local/share/applications/*.desktop; do
  if grep -q 'Exec=chromium .*--app=' "$desktop_file"; then
    url=$(grep '^Exec=' "$desktop_file" | sed -n 's/.*--app="\?\([^"]*\)"\?.*/\1/p')
    sed -i "s|^Exec=.*|Exec=omarchy-launch-webapp \"$url\"|" "$desktop_file"
  fi
done
# Update Hyprland keybindings
HYPR_BINDINGS_FILE="$HOME/.config/hypr/bindings.conf"
if [ -f "$HYPR_BINDINGS_FILE" ]; then
  sed -i 's/\$browser =.*$/\$browser = omarchy-launch-browser/' "$HYPR_BINDINGS_FILE"
  sed -i 's/\$webapp="/omarchy-launch-webapp "/g' "$HYPR_BINDINGS_FILE"
  sed -i '/^\$webapp = \$browser --app/d' "$HYPR_BINDINGS_FILE"
fi

What it does:

  • Scans .desktop files for Chromium --app invocations; swaps them for omarchy-launch-webapp.
  • Updates Hyprland’s $browser and $webapp variables to the new helpers.

Quality-of-Life Changes

Omarchy ships many small migrations to refine the user experience. Examples include:

  • Install xmlstarlet for font updates. (1754509222.sh)
  • Tune MTU probing for reliable SSH. (1754668999.sh)
  • Disable networkd-wait-online for faster boots. (1754856741.sh)
  • Add Android MTP support via gvfs-mtp. (1754221967.sh)
  • Migrate fonts from manual downloads to Arch packages. (1753908454.sh)

These migrations demonstrate Omarchy’s commitment to continuous improvement and sensible defaults.

With this pipeline and migrations framework, Omarchy keeps your Arch Linux desktop curated, up-to-date, and aligned with evolving best practices—all with minimal manual intervention.