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

> Restart the Omarchy shell safely using omarchy-restart-shell. This process coordinates Hyprland and Quickshell for a fresh UI instance. Learn safe restart procedures.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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](https://github.com/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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-restart-shell#L8-L13)【8-13】:

```bash

# 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】:

```bash

# 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】:

```bash

# 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

```bash

# 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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-restart-shell) | Main orchestration script with lock-aware restart logic |
| [`bin/omarchy-shell`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-shell) | CLI wrapper providing `ping`, `lock status`, and other shell commands |
| [`bin/omarchy-launch-shell`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-launch-shell) | Hyprland integration helper that spawns new Quickshell instances |
| [`bin/omarchy-hyprland-session-locked`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-hyprland-session-locked) | Lock state detector for the Hyprland session |
| [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml) | Primary QML definition loaded by Quickshell |
| [`default/omarchy/omarchy-menu.jsonc`](https://github.com/omacom/omarchy/blob/quattro/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`](https://github.com/omacom/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc), which binds the UI action to the `omarchy-restart-shell` command for convenient access without terminal use.