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

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, 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 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:

# 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 – Hyprland autostart hook responsible for invoking the launch command on session initialization.
• docs/omarchy-shell.md – User-facing documentation detailing manual launch and restart procedures.
• 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 – Automated test confirming the restart script correctly respawns the shell without session loss.
• 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 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 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.

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