How to Restart the Omarchy Shell: Safe Restart Procedures for Quickshell UI

Restart the Omarchy shell by running omarchy-restart-shell, which safely coordinates Hyprland, session locks, and Quickshell processes to bring up a fresh UI instance.

The Omarchy shell is a Quickshell-based UI that runs inside a Hyprland compositor session. Understanding how to properly restart it prevents deadlocks, preserves security state, and ensures your desktop environment remains stable. This guide explains the complete restart flow as implemented in the omacom/omarchy repository.

Prerequisites for Restarting the Omarchy Shell

Before attempting to restart the Omarchy shell, ensure your system meets these conditions:

• Hyprland session is active and accessible
• OMARCHY_PATH environment variable is defined (either in systemd user environment or current shell)
• shell/shell.qml exists at the configured path

The restart script validates these requirements automatically. If OMARCHY_PATH is missing from the systemd user environment, it falls back to the current environment variable. These checks appear in bin/omarchy-restart-shell【8-13】:

# OMARCHY_PATH discovery from systemd or fallback

OMARCHY_PATH=$(systemctl --user show-environment | grep 'OMARCHY_PATH=' | cut -d= -f2-)
[ -z "$OMARCHY_PATH" ] && OMARCHY_PATH="${OMARCHY_PATH:-$OMARCHY_PATH}"

Handling Remote and SSH Sessions

When you restart the Omarchy shell from outside the session—such as over SSH—the script must discover which Hyprland instance to target. It finds the newest Hyprland runtime directory and exports HYPRLAND_INSTANCE_SIGNATURE accordingly【16-19】:

# Restart from SSH - automatic Hyprland discovery

ssh user@host 'omarchy-restart-shell'

This ensures hyprctl commands affect the correct compositor even when no local Hyprland environment exists.

Session Lock Safety Checks

The Omarchy shell restart procedure includes mandatory lock verification to prevent security vulnerabilities. The script uses omarchy-hyprland-session-locked to detect lock state, then queries detailed status via omarchy-shell lock status.

Blocked Restart Conditions

If the lock reports secure or requested, the restart aborts immediately to avoid killing the lock client【28-36】. This prevents accidentally exposing a locked session.

Post-Restart Lock Recovery

When a restart proceeds from an unlocked state, the script sets relock=1 and uses the relock_session helper function. This polls until the lock becomes secure again, re-issuing lock requests as needed【45-61】.

Terminating Existing Shell Processes

To prevent duplicate UI instances, the restart script aggressively cleans up running Quickshell processes. It repeatedly executes quickshell kill until no matching processes remain【64-66】:

# Kill loop ensures complete cleanup

while quickshell kill -p "$CONFIG_DIR" --any-display 2>/dev/null; do
    sleep 0.1
done

The --any-display flag targets Quickshell instances regardless of which display they're bound to.

Launching the Fresh Omarchy Shell

With cleanup complete, the script requests Hyprland to execute omarchy-launch-shell【68-71】. This helper binary starts a new Quickshell instance that inherits the session's full environment, including the verified OMARCHY_PATH.

Health Verification and Service Recovery

The restart procedure confirms success through active health checks:

1. Ping verification — Up to 20 attempts using omarchy-shell shell ping【72-88】
2. Invitation service restart — Pending omarchy-*-invitation.service units are restarted via systemctl --user try-restart
3. Timeout handling — If the shell never responds, the script exits non-zero with an error message【92-94】

Complete Command Reference

# Standard restart (recommended)

omarchy-restart-shell

# With explicit path override

OMARCHY_PATH=$HOME/.local/share/omarchy omarchy-restart-shell

# Remote execution

ssh desktop 'export OMARCHY_PATH=/home/user/.local/share/omarchy && omarchy-restart-shell'

Key Source Files for Omarchy Shell Restart

Path	Purpose
bin/omarchy-restart-shell	Main orchestration script with lock-aware restart logic
bin/omarchy-shell	CLI wrapper providing ping, lock status, and other shell commands
bin/omarchy-launch-shell	Hyprland integration helper that spawns new Quickshell instances
bin/omarchy-hyprland-session-locked	Lock state detector for the Hyprland session
shell/shell.qml	Primary QML definition loaded by Quickshell
default/omarchy/omarchy-menu.jsonc	Menu configuration exposing "Restart Shell" to users

Summary

• Primary command: omarchy-restart-shell handles the complete restart flow
• Lock safety: Restarts are blocked when session lock is secure or requested, with automatic relock after successful restart
• Process cleanup: Aggressive quickshell kill loop prevents duplicate shell instances
• Health verification: Ping-based confirmation ensures the new shell is responsive before completing
• Remote support: Automatic HYPRLAND_INSTANCE_SIGNATURE detection enables SSH-based restarts

Frequently Asked Questions

Why does my Omarchy shell restart fail with a lock error?

The restart aborts when omarchy-shell lock status reports secure or requested. This protects against killing the lock client while your session should remain protected. Unlock your session first, or wait for any pending lock operation to complete.

Can I restart the Omarchy shell while logged in via SSH?

Yes. The omarchy-restart-shell script automatically discovers the active Hyprland instance by examining runtime directories and exporting HYPRLAND_INSTANCE_SIGNATURE. This allows remote restarts without local graphical access.

What happens to my pending invitations when the shell restarts?

All omarchy-*-invitation.service units are automatically restarted with systemctl --user try-restart once the new shell passes its health check. Your invitation workflows survive the transition.

Where is the "Restart Shell" menu option defined?

The menu entry appears in default/omarchy/omarchy-menu.jsonc, which binds the UI action to the omarchy-restart-shell command for convenient access without terminal use.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}