# How Omarchy Launches and Restarts Its Desktop Shell: Complete Technical Guide

> Learn how Omarchy launches and restarts its desktop shell using a bin/omarchy-shell wrapper script. Discover full restarts and lightweight config reloads.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

**The Omarchy desktop shell uses a `bin/omarchy-shell` wrapper script to launch Quickshell with `shell.qml`, and supports both full restarts via `SIGTERM` + re-execution and lightweight config reloads through IPC commands.**

The **Omarchy** desktop environment is built on **Quickshell**, a QML-based compositor. Understanding how the shell starts and recovers is essential for troubleshooting crashes, developing plugins, or automating deployments. This guide examines the actual implementation in the `omacom/omarchy` repository.

## How Omarchy Shell Launch Works

### Entry Point: `bin/omarchy-shell`

All shell lifecycle operations flow through the helper script at [`bin/omarchy-shell`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-shell). This script performs three critical functions before handing control to Quickshell:

1. **Lockfile verification** — Checks `$XDG_RUNTIME_DIR/omarchy-shell.lock` to prevent duplicate instances
2. **Environment setup** — Exports `OMARCHY_PATH` and updates `$PATH` to include `bin/`
3. **Process execution** — Spawns Quickshell with the main QML entry point

The core exec call follows this pattern:

```bash
exec "$(command -v quickshell)" \
    --qml "$(realpath "$OMARCHY_PATH/shell/shell.qml")"

```

This replaces the shell process with Quickshell, making `omarchy-shell` a true launcher rather than a persistent parent.

### QML Initialization in `shell.qml`

The [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml) file serves as the top-level QML component. It:

- Builds the desktop UI (panels, widgets, wallpapers)
- Registers service objects for IPC communication
- Establishes the `OmarchyShell` component with bidirectional message channels

After spawning, the launcher writes the Quickshell PID to the lockfile, enabling later control commands to locate the running instance.

## Omarchy Shell Restart Mechanisms

The repository implements **two distinct restart strategies** depending on whether you need a full process recycle or a configuration refresh.

### Method 1: Full Process Restart

**`omarchy-shell restart`** (or `omarchy-shell -r`) performs a hard restart:

- Reads PID from `$XDG_RUNTIME_DIR/omarchy-shell.lock`
- Sends `SIGTERM` or `SIGINT` to the Quickshell process
- Immediately re-executes the launch sequence described above

This method guarantees a clean state—useful after plugin installations, Quickshell updates, or crash recovery. The implementation resides entirely within [`bin/omarchy-shell`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-shell).

### Method 2: Lightweight Config Reload

**`omarchy-shell reloadConfig`** uses IPC for faster turnaround:

- Sends message `omarchy-shell shell reloadConfig` to the running instance
- The QML component catches this via its IPC channel
- Either re-loads the QML tree in-place or triggers `Qt.quit()` followed by controlled restart

This approach preserves window states and connected clients where possible. The IPC infrastructure leverages utilities in [`shell/Commons/Util.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/Commons/Util.qml).

### Restart Test Coverage

Automated verification exists at [[`test/shell.d/restart-shell-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/restart-shell-test.sh)](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/restart-shell-test.sh). This test validates that:

- Lockfiles are properly cleaned on exit
- The restart command successfully spawns a new process
- IPC channels remain functional across reloads

## Practical Commands for Shell Control

```bash

# Start shell (typically invoked by session manager, not manually)

omarchy-shell

# Full restart after configuration changes or crashes

omarchy-shell restart

# Quick reload without dropping windows or connections

omarchy-shell reloadConfig

# Verify shell responsiveness

omarchy-shell shell ping

```

## Supporting Configuration

| File | Role in Launch/Restart |
|------|------------------------|
| [`bin/omarchy-shell`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-shell) | Primary launcher with sub-commands for restart and IPC |
| [`bin/omarchy-shell-config`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-shell-config) | Pre-launch configuration copier; seeds `~/.config/omarchy` with defaults |
| [`shell/shell.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/shell.qml) | Quickshell entry point; handles UI construction and IPC message dispatch |
| [`shell/Commons/Util.qml`](https://github.com/omacom/omarchy/blob/quattro/shell/Commons/Util.qml) | Shared utilities for environment queries and IPC operations |

## Summary

- **Launch** — `omarchy-shell` prepares environment, validates lockfile, and execs Quickshell with `shell.qml`
- **Full restart** — `omarchy-shell restart` terminates and respawns the entire process tree
- **Config reload** — `omarchy-shell reloadConfig` uses IPC to refresh QML without full restart
- **Lockfile management** — PID tracking at `$XDG_RUNTIME_DIR/omarchy-shell.lock` enables reliable process control
- **Test coverage** — [`test/shell.d/restart-shell-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/restart-shell-test.sh) automates restart validation

## Frequently Asked Questions

### What happens if I run `omarchy-shell` while the desktop is already running?

The launcher detects the existing lockfile and exits with a message rather than spawning a second instance. Use `omarchy-shell restart` or `omarchy-shell reloadConfig` to affect the running shell.

### Does Omarchy preserve window state across restarts?

**Full restarts** (`omarchy-shell restart`) terminate Quickshell completely—window state depends on your compositor's session restoration. **Config reloads** (`reloadConfig`) attempt to preserve state by re-loading QML in-place where Quickshell supports it.

### Where does Omarchy store its lockfile and runtime state?

The lockfile is written to `$XDG_RUNTIME_DIR/omarchy-shell.lock`. User configuration is managed in `~/.config/omarchy`, with defaults seeded by `omarchy-shell-config` on first launch.

### How can I debug why the shell fails to start?

Check lockfile presence manually, verify `OMARCHY_PATH` points to valid installation files, and ensure `quickshell` binary is in `$PATH`. The `omarchy-shell` script performs these validations and reports specific failures before attempting execution.