# How to Launch or Restart the Omarchy Shell: Complete Guide

> Learn how to launch or restart the Omarchy shell using omarchy-launch-shell and omarchy-restart-shell. Preserve your Hyprland session with this complete guide.

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

---

**Use `omarchy-launch-shell` to start the Omarchy shell and `omarchy-restart-shell` to safely stop and restart it while preserving your Hyprland session.**

The Omarchy shell serves as the long-running core of the Omarchy declarative desktop environment, hosting first-party plugins and providing IPC capabilities through Quickshell. Whether you are configuring a fresh Hyprland session or applying changes to QML configuration files, understanding how to properly launch or restart the Omarchy shell ensures your desktop remains responsive and synchronized with your configuration.

## Starting the Shell with omarchy-launch-shell

The primary entry point for initializing the shell is the helper script **`omarchy-launch-shell`**, located at `bin/omarchy-launch-shell` in the repository. This script orchestrates the startup sequence by spawning the `omarchy-shell` daemon and registering it with the Hyprland window manager via Quickshell.

When executed, `omarchy-launch-shell` performs three critical operations:

- Spawns `omarchy-shell` as a background daemon
- Registers the new shell instance with Hyprland using the command `hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'`
- Writes the process ID to `$HOME/.local/state/omarchy/shell.pid` for lifecycle management

To launch the shell manually from a terminal:

```bash

# Start the shell in the background

$ omarchy-launch-shell &

```

Typically, this command is invoked automatically during login via an autostart script rather than manually.

## Restarting Safely with omarchy-restart-shell

When modifying QML files in `shell/shell.qml` or recovering from an unresponsive desktop, use **`omarchy-restart-shell`** to gracefully cycle the shell process. This script, located at `bin/omarchy-restart-shell`, ensures a clean shutdown before starting a fresh instance, preventing zombie processes and socket conflicts at `$XDG_RUNTIME_DIR/omarchy-shell.sock`.

The restart workflow follows this sequence:

1. Locates the existing PID via `$HOME/.local/state/omarchy/shell.pid`
2. Sends `SIGTERM` to the running process and waits for exit
3. Clears the lock file at `$HOME/.local/state/omarchy/restart-shell-called` to prevent stale locks
4. Invokes `omarchy-launch-shell` while preserving the `$OMARCHY_PATH` environment variable

Execute the restart from any terminal:

```bash

# Safely restart to apply QML changes or recover from hangs

$ omarchy-restart-shell

```

## Runtime IPC and Verification

Once active, the shell exposes an IPC interface through the **`omarchy-shell`** binary. This client communicates via a Unix socket at `$XDG_RUNTIME_DIR/omarchy-shell.sock` and routes commands to appropriate QML plugins through the Quickshell IPC bridge.

Verify that the shell is responsive:

```bash
$ omarchy-shell shell ping

```

Refresh specific widgets without a full restart:

```bash
$ omarchy-shell -q omarchy.clock refresh

```

## Key Files and State Management

The shell maintains runtime state in `$HOME/.local/state/omarchy/`:

| Component | Source Path | Purpose |
|-----------|-------------|---------|
| Launch script | `bin/omarchy-launch-shell` | Spawns daemon and registers with Hyprland |
| Restart script | `bin/omarchy-restart-shell` | Manages graceful shutdown using lock files |
| IPC binary | `bin/omarchy-shell` | Unix socket client for runtime commands |
| UI definition | `shell/shell.qml` | Core QML loaded by Quickshell |
| PID file | `$HOME/.local/state/omarchy/shell.pid` | Tracks active shell process |

## Summary

- **`omarchy-launch-shell`** initiates the Omarchy shell process, registers it with Hyprland via `hyprctl dispatch`, and writes the PID to `$HOME/.local/state/omarchy/shell.pid`
- **`omarchy-restart-shell`** safely terminates the existing shell using the PID file, clears the lock at `$HOME/.local/state/omarchy/restart-shell-called`, and starts a fresh instance
- The **`omarchy-shell`** binary provides runtime IPC via Unix socket at `$XDG_RUNTIME_DIR/omarchy-shell.sock`
- Always use `omarchy-restart-shell` rather than manually killing the process to ensure proper cleanup of Quickshell resources and Hyprland registration

## Frequently Asked Questions

### How do I know if the Omarchy shell is running?

Check for the process and test the IPC endpoint. Run `omarchy-shell shell ping` in a terminal. If the shell is active, it returns "omarchy-shell is ready". You can also verify the PID file exists at `$HOME/.local/state/omarchy/shell.pid` and that the process is listed in `ps aux | grep omarchy-shell`.

### Can I restart the shell without losing my Hyprland windows?

Yes. The `omarchy-restart-shell` script only terminates the Quickshell-based UI layer defined in `shell/shell.qml`, not the Hyprland compositor itself. Your windows and layout remain intact because the restart affects only the `omarchy-shell` process that renders widgets and handles IPC, leaving the Wayland session untouched.

### Where does Omarchy store the shell process ID?

The active shell PID is written to `$HOME/.local/state/omarchy/shell.pid`. This file is created by `omarchy-launch-shell` at startup and referenced by `omarchy-restart-shell` during shutdown. The state directory also contains lock files that prevent race conditions during restart operations.

### What should I do if omarchy-restart-shell hangs?

If the restart script freezes, manually remove the lock file at `$HOME/.local/state/omarchy/restart-shell-called` and kill any existing `omarchy-shell` processes using `kill -9 $(cat ~/.local/state/omarchy/shell.pid)`. Then run `omarchy-launch-shell` directly. This recovers from scenarios where the shell died without cleaning up its lock files.