# How to Launch and Restart the Omarchy Shell: A Complete Guide

> Learn how to launch and restart the Omarchy shell. Easily respawn the Quickshell process with omarchy-restart-shell, preserving your Hyprland session state.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-25

---

**To launch the Omarchy shell, run `omarchy-launch-shell`; to restart it without logging out, run `omarchy-restart-shell`, which uses `hyprctl` to respawn the Quickshell process while preserving your Hyprland session state.**

The Omarchy desktop environment by **basecamp/omarchy** provides a Quickshell-based graphical interface that requires specific lifecycle commands to start and respawn correctly. Understanding how to properly launch and restart the Omarchy shell ensures you can initialize sessions after reboot and reload configuration changes on the fly without disrupting your compositor layout.

## Launching the Omarchy Shell

The Omarchy shell runs as a **Quickshell** QML process managed by the **Hyprland** compositor. The launch mechanism relies on helper scripts in the `bin/` directory that prepare the runtime environment and delegate process management to Hyprland via `hyprctl` dispatches.

### The `omarchy-launch-shell` Command

Located at `bin/omarchy-launch-shell`, this script performs three critical initialization tasks:

1. Exports required environment variables, including `OMARCHY_PATH` and `OMARCHY_CONFIG`
2. Loads the user's shell configuration from `~/.config/omarchy/shell.json`
3. Invokes `hl.exec_cmd("omarchy-launch-shell")` through `hyprctl` so the compositor owns the new process

If Hyprland is not yet ready, the script implements a back-off retry loop until the shell successfully attaches to the compositor.

### Automatic Startup with Hyprland

According to the source in [`default/hypr/autostart.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/autostart.lua), the launch command is invoked automatically when Hyprland initializes. This autostart hook ensures the shell spawns immediately after login without manual intervention, reading the default configuration from [`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json) before loading the main QML entry point at `shell/shell.qml`.

## Restarting the Omarchy Shell

When you modify plugins, edit QML files, or need to recover from a frozen session, you must restart the shell to apply changes. The restart command ensures a clean handoff that preserves your monitor layout and output configuration.

### The `omarchy-restart-shell` Mechanism

The `bin/omarchy-restart-shell` script sends a Hyprland dispatch that:

1. Kills the current Quickshell process
2. Immediately executes `hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'`
3. Guarantees the new instance inherits the existing compositor state, including output layout and monitor configuration

This method is the recommended way to recover from crashes or reload shell code without logging out, as it leverages Hyprland's process management rather than external signaling.

## Practical Command Examples

Use these commands in a terminal or TTY to manage the shell lifecycle:

```bash

# Start a fresh shell instance after a reboot or if the shell is not running

omarchy-launch-shell

# Restart the shell to apply configuration changes or recover from unresponsiveness

omarchy-restart-shell

# Debug the launch process with verbose shell output

set -x
omarchy-launch-shell

```

## Key Source Files and Testing

The Omarchy repository includes comprehensive test coverage for shell lifecycle management. These files define the behavior you interact with when launching and restarting:

- **`bin/omarchy-launch-shell`** – Core script that prepares the environment and asks Hyprland to start the Quickshell process.
- **`bin/omarchy-restart-shell`** – Wrapper that dispatches the replacement command to the compositor.
- **[`default/hypr/autostart.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/autostart.lua)** – Hyprland autostart hook responsible for invoking the launch command on session initialization.
- **[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)** – User-facing documentation detailing manual launch and restart procedures.
- **[`test/shell.d/launch-shell-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/launch-shell-test.sh)** – Automated validation ensuring the launch script works under various startup conditions.
- **[`test/shell.d/restart-shell-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/restart-shell-test.sh)** – Automated test confirming the restart script correctly respawns the shell without session loss.
- **[`config/omarchy/shell.json`](https://github.com/basecamp/omarchy/blob/main/config/omarchy/shell.json)** – Default configuration template read by the launch script during initialization.
- **`shell/shell.qml`** – The primary QML entry point loaded when the shell starts.

## Summary

- Use **`omarchy-launch-shell`** to start the Quickshell process with proper environment variables (`OMARCHY_PATH`, `OMARCHY_CONFIG`) and configuration from `~/.config/omarchy/shell.json`.
- Use **`omarchy-restart-shell`** to kill the current shell and respawn it via `hyprctl dispatch`, preserving your Hyprland compositor state.
- Both commands reside in the `bin/` directory and are invoked automatically by [`default/hypr/autostart.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/autostart.lua) during login.
- Test suites in `test/shell.d/` verify both launch and restart reliability.

## Frequently Asked Questions

### What is the difference between `omarchy-launch-shell` and `omarchy-restart-shell`?

The launch command initializes a fresh Quickshell instance and is used for initial startup or when no shell is currently running. The restart command first terminates the existing shell process, then triggers a new launch via `hyprctl dispatch`, ensuring configuration changes take effect immediately without requiring you to log out.

### Where does Omarchy store the shell launch commands?

Both commands are located in the `bin/` directory of the repository. The `bin/omarchy-launch-shell` script handles environment setup, variable export, and Hyprland integration, while `bin/omarchy-restart-shell` manages the respawn dispatch that preserves your session context.

### How does Omarchy automatically start the shell when I log in?

The file [`default/hypr/autostart.lua`](https://github.com/basecamp/omarchy/blob/main/default/hypr/autostart.lua) contains the autostart hook that executes `omarchy-launch-shell` when Hyprland initializes. This hook reads your user configuration from `~/.config/omarchy/shell.json` and sets variables like `OMARCHY_PATH` before loading the QML interface.

### What should I do if the Omarchy shell crashes or becomes unresponsive?

Run `omarchy-restart-shell` from a terminal or TTY. This command uses `hyprctl dispatch 'hl.dsp.exec_cmd("omarchy-launch-shell")'` to kill the frozen process and immediately spawn a replacement, ensuring you retain your compositor layout and monitor settings while recovering the shell.