# How to Restart the Omarchy Shell: Complete Command Guide

> Safely restart the Omarchy shell with the omarchy-restart-shell command. Learn to terminate processes and launch new sessions with automatic lock file cleanup.

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

---

**Run `omarchy-restart-shell` from your terminal to safely terminate the current Quickshell process and launch a fresh Omarchy session while handling lock file cleanup automatically.**

The Omarchy desktop environment from basecamp/omarchy renders its user interface through a **Quickshell** process that maintains state in `~/.local/state/omarchy/`. When you need to restart the Omarchy shell after updating QML plugins, editing configuration files, or recovering from a frozen session, using the dedicated restart command ensures proper lock management and prevents race conditions.

## Understanding the Omarchy Shell Architecture

The Omarchy shell relies on a file-based locking mechanism to prevent multiple instances from running simultaneously. The shell creates a lock file at `$HOME/.local/state/omarchy/shell.lock` during startup and removes it upon termination. According to the source code in [`bin/omarchy-restart-shell`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-restart-shell), the restart sequence must coordinate with this lock system to avoid conflicts with the **Quickshell** process manager.

When the shell becomes unresponsive or you modify core QML components, a simple process kill leaves stale lock files that prevent new instances from launching. The `omarchy-restart-shell` command handles these edge cases by implementing atomic restart locks and stale file detection.

## Using the omarchy-restart-shell Command

The primary method to restart the Omarchy shell is the **`omarchy-restart-shell`** utility located in [`bin/omarchy-restart-shell`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-restart-shell). This script provides a safe wrapper around the shell lifecycle.

### The Four-Stage Restart Process

The command executes a deterministic sequence to ensure clean state transitions:

1. **Acquire the restart lock** – The script creates an atomic lock to prevent concurrent restart attempts from multiple processes.

2. **Terminate the current Quickshell instance** – It signals the running shell to exit, which triggers cleanup of the shell lock file at `$HOME/.local/state/omarchy/shell.lock`.

3. **Launch a fresh shell** – Upon confirmation of the previous process termination, it invokes [`omarchy-launch-shell`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-launch-shell) to instantiate a new Quickshell session and regenerate the lock file.

4. **Fail-safe recovery** – If the shell crashed and left a stale lock file, the command detects this condition and forcibly cleans up the orphaned lock before starting the new instance, as verified in [[`test/shell.d/restart-shell-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/restart-shell-test.sh)](https://github.com/basecamp/omarchy/blob/quattro/test/shell.d/restart-shell-test.sh).

### Basic Usage

Execute the restart from any terminal emulator:

```bash
omarchy-restart-shell

```

The command returns only after the new shell has successfully acquired its lock file and initialized the Quickshell runtime.

## Scripting and Automation Integration

You can integrate the restart command into configuration reload workflows or update scripts. The [`bin/omarchy-update-restart`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy-update-restart) script demonstrates this pattern by calling `omarchy-restart-shell` as part of system update procedures.

### Conditional Restart After Configuration Changes

Use this pattern to reload the shell only when custom configuration exists:

```bash
if [[ -f "$HOME/.config/omarchy/shell.json" ]]; then
    echo "Reloading Omarchy shell..."
    omarchy-restart-shell
fi

```

### Error Handling in Scripts

When invoking the restart from other Omarchy commands, capture failures gracefully:

```bash
omarchy-restart-shell || echo "Failed to restart the shell"

```

## UI Menu Integration

The restart command is exposed through the default application menu defined in [`default/omarchy/omarchy-menu.jsonc`](https://github.com/basecamp/omarchy/blob/quattro/default/omarchy/omarchy-menu.jsonc) (line 356). Users can trigger a shell restart without opening a terminal by selecting the restart option from the Omarchy menu, which executes `omarchy-restart-shell` in the background.

Additional documentation appears in [[`docs/omarchy-shell.md`](https://github.com/basecamp/omarchy/blob/main/docs/omarchy-shell.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/omarchy-shell.md), which describes both manual and programmatic restart methods for the Quickshell-based desktop environment.

## Summary

- **`omarchy-restart-shell`** is the canonical command to restart the Omarchy shell safely.
- The command manages the **Quickshell** lock file at `~/.local/state/omarchy/shell.lock` to prevent race conditions.
- It implements a four-stage process: acquire lock, terminate old process, launch new shell, and recover from stale locks.
- The restart utility is available in the UI menu and referenced throughout the codebase, including update scripts and automated tests.

## Frequently Asked Questions

### What is the fastest way to restart the Omarchy shell?

Run `omarchy-restart-shell` from any terminal. This immediately terminates the current Quickshell process and spawns a new instance without requiring a full system logout. The command handles lock file cleanup automatically, making it faster and safer than manually killing the process.

### Where does Omarchy store its shell lock files?

The shell maintains its runtime lock at `$HOME/.local/state/omarchy/shell.lock`. The restart command checks this location to determine if a Quickshell instance is currently active and removes stale locks if the process crashed without cleaning up its state files.

### Can I restart the Omarchy shell if it has crashed?

Yes. The `omarchy-restart-shell` command includes fail-safe logic to detect and remove stale lock files left by crashed processes. As implemented in the test suite at [`test/shell.d/restart-shell-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/restart-shell-test.sh), the command will clean up orphaned locks and launch a fresh shell even when the previous instance did not shut down cleanly.

### How do I invoke a restart from the Omarchy menu?

Select the restart option from the default application menu. The menu entry is defined in `default/omarchy/omarchy-menu.jsonc` at line 356 and executes `omarchy-restart-shell` in the background, allowing you to restart the desktop environment without opening a terminal window.