Troubleshooting and Recovery

When a reboot or relaunch is required

Index

1. Overview
2. State Flags and Markers
3. Detection Logic
4. Migrations Triggering Relaunch
5. Installation Finish: Automatic Reboot
6. Restarting Specific Services
7. How to Invoke Recovery Actions

---

Overview

Omarchy automatically detects when system updates or configuration changes require either a full system reboot or a Hyprland relaunch. It also supports targeted restarts of individual components (e.g., Waybar, Swayosd).

These mechanisms ensure that:

• Kernel upgrades become effective
• Hyprland picks up new environment variables or theme changes
• Critical services restart without manual intervention

---

State Flags and Markers

Omarchy uses state files under ~/.local/state/omarchy/ to track required recovery actions.

State File	Purpose
reboot-required	Indicates pending full system reboot
relaunch-required	Indicates Hyprland must relaunch
restart--required	Indicates a specific service must restart

• Files are created by migrations or update routines.
• omarchy-state clear <flag> resets the corresponding state.

---

Detection Logic

The core of recovery detection lives in the omarchy-update-restart script. It runs automatically at the end of omarchy-update:

#!/bin/bash
# Kernel change? Prompt reboot
if [ "$(uname -r | sed 's/-arch/\.arch/')" != "$(pacman -Q linux | awk '{print $2}')" ]; then
  gum confirm "Linux kernel has been updated. Reboot?" \
    && omarchy-state clear re*-required && sudo reboot now

# Generic reboot flag?
elif [ -f "$HOME/.local/state/omarchy/reboot-required" ]; then
  gum confirm "Updates require reboot. Ready?" \
    && omarchy-state clear re*-required && sudo reboot now

# Hyprland relaunch needed?
elif [ -f "$HOME/.local/state/omarchy/relaunch-required" ]; then
  gum confirm "Updates require Hyprland relaunch. Ready?" \
    && omarchy-state clear re*-required && uwsm stop
fi

# Restart individual services
for file in "$HOME"/.local/state/omarchy/restart-*-required; do
  if [ -f "$file" ]; then
    service=$(basename "$file" | sed 's/restart-\(.*\)-required/\1/')
    echo "Restarting $service"
    omarchy-state clear "$(basename "$file")"
    omarchy-restart-"$service"
  fi
done

• Kernel change detection compares uname -r vs. pacman -Q linux .
• Reboot/relaunch flags trigger user confirmation via gum.
• Service restarts loop through restart-*-required flags and invoke corresponding omarchy-restart-<service> commands.

---

Migrations Triggering Relaunch

Certain migrations require Hyprland to reload so that new environment settings take effect. Example:

#!/bin/bash
# After adding UWSM to PATH:
echo -e "\nOmarchy bins have been added to PATH...  
You must immediately relaunch Hyprland..."
gum confirm "Ready to relaunch Hyprland? (All applications will be closed)" \
  && touch ~/.local/state/omarchy/migrations/1751134560.sh \
  && uwsm stop

• Creates the relaunch-required flag.
• Provides a direct prompt to the user.

---

Installation Finish: Automatic Reboot

At the end of a fresh install, Omarchy displays a splash and reboots automatically:

#!/bin/bash
tte -i ~/.local/share/omarchy/logo.txt ...
echo "You're done! So we're ready to reboot now..."
sleep 5
reboot

• Removes installer sudoers fragment before reboot.
• Warns user to remove USB installer.

---

Restarting Specific Services

Omarchy supports fine-grained restarts of various components. For each service, there is an omarchy-restart-<service> script in bin/. Common examples:

Service	Script	Action
Waybar	omarchy-restart-waybar	Sends SIGUSR2 or restarts Waybar
Swayosd	omarchy-restart-swayosd	Restarts SwayOSD service
Hypridle	omarchy-restart-hypridle	Dispatches Hyprland idle reload
Hyprsunset	omarchy-restart-hyprsunset	Dispatches Hyprland theme reload
Walker	omarchy-restart-walker	Restarts Walker menu
Wi-Fi	omarchy-restart-wifi	systemctl restart NetworkManager (*)
Bluetooth	omarchy-restart-bluetooth	systemctl restart bluetooth.service

(*) Actual implementation may vary by distribution.

---

How to Invoke Recovery Actions

1. Run a full update:

   omarchy-update
   

2. At the end, omarchy-update-restart evaluates conditions.
3. Confirm when prompted by gum.
4. Omarchy will perform the action and clear the corresponding flags.

Pro tip: You can manually check and clear flags:

ls ~/.local/state/omarchy
# Clear all flags
omarchy-state clear re*-required

---

By automating reboot, relaunch, and targeted service restarts, Omarchy ensures your Arch Linux desktop remains consistent and up-to-date with minimal manual intervention.