# Creating a Custom Omarchy Lock Screen Theme with shell.lock.toml

> Create a custom Omarchy lock screen theme using shell.lock.toml. Override wallpapers, colors, and effects to personalize your Quickshell experience.

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

---

**You create a custom Omarchy lock screen by adding a [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) file to your theme directory, which Quickshell merges with your base theme configuration to override wallpapers, colors, and lock-specific visual effects.**

Omarchy renders its lock screen through the **Quickshell** UI layer, allowing deep customization via TOML configuration. When the screen locks, the system looks for [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) inside the currently active theme folder—such as [`themes/tokyo-night/shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/themes/tokyo-night/shell.lock.toml)—and merges its values with the standard theme definitions. This architecture lets you inherit fonts, icons, and base colors from your main theme while specifying distinct backgrounds or blur settings that only appear on the lock screen.

## How the Omarchy Lock Screen System Works

The lock screen initialization follows a explicit merge pattern implemented in the Quickshell plugin layer. When the session locks, `shell/plugins/lock/Service.qml` loads the active theme and checks for the presence of [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml).

If the file exists, the service merges its key-value pairs with the general theme data:

- **Override behavior**: Any key defined in [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) takes precedence over the same key in the base theme configuration.
- **Fallback behavior**: Missing keys automatically inherit values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and other standard theme assets.
- **Rendering**: `shell/plugins/lock/LockView.qml` consumes this merged configuration to render the background image or video, clock styling, and transparency effects.

Because the lock screen uses the same theme engine as the desktop shell, you only need to specify the properties you want to change rather than duplicating the entire theme definition.

## Step-by-Step: Creating a Custom Lock Screen Theme

### Copy a Base Theme

Start by duplicating an existing theme to ensure you inherit all required assets and structure:

```bash
cp -r "$(omarchy-path)/themes/tokyo-night" \
  "$HOME/.config/omarchy/themes/my-custom-lock"

```

This command copies the Tokyo Night theme into your user configuration directory, preserving the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), icon definitions, and QML references while giving you a sandbox to modify lock-specific settings.

### Create the shell.lock.toml Configuration

Navigate to your new theme folder and create the lock-specific configuration file:

```bash
touch "$HOME/.config/omarchy/themes/my-custom-lock/shell.lock.toml"

```

The file name must match exactly—[`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml)—as `Service.qml` specifically searches for this filename when initializing the lock view. Any other filename will be ignored by the loader.

### Configure Wallpapers and Visual Overrides

Open [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) and define your lock-screen-specific properties. You can set static wallpapers, video backgrounds, color overrides, and boolean flags for visual effects:

```toml
wallpaper = "/usr/share/backgrounds/secure-workspace.jpg"

# video = "/usr/share/backgrounds/matrix-rain.mp4"

[colors]
clock_text = "#e0f7fa"
background_overlay = "#00000080"

blur_enabled = false

```

- The `wallpaper` key accepts absolute paths to image files.
- The optional `video` key enables animated backgrounds supported by the Quickshell media layer.
- Color values under `[colors]` override the palette only for lock screen widgets.
- Boolean flags like `blur_enabled` control GPU effects without affecting the desktop theme.

### Activate and Test

Apply your custom theme using the Omarchy CLI:

```bash
omarchy-theme-set my-custom-lock

```

To verify your configuration without locking your session, use the preview command if available, or trigger a screen lock with:

```bash
loginctl lock-session

```

## Minimal Configuration Example

For a minimal setup that changes only the lock screen wallpaper and disables blur, create `~/.config/omarchy/themes/minimal-lock/shell.lock.toml` with the following content:

```toml
wallpaper = "/home/user/pictures/lock-wallpaper.png"

[colors]
clock_text = "#ffffff"

blur_enabled = false

```

This configuration inherits all fonts, icon themes, and base colors from the parent theme while applying the custom background and crisp text rendering specific to the lock screen.

## Key Source Files in omacom/omarchy

Understanding the source layout helps you debug and extend your custom themes:

- **`shell/plugins/lock/Service.qml`**: Loads the active theme, locates [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml), and executes the configuration merge before initializing the lock view.
- **`shell/plugins/lock/LockView.qml`**: The QML component that reads the merged theme data and renders the background media, clock, and unlock interface.
- **[`themes/tokyo-night/shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/themes/tokyo-night/shell.lock.toml)**: Reference implementation showing production-ready lock screen configuration with video background support and color overrides.
- **`bin/omarchy-theme-set`**: Command-line utility that updates the active theme symlink and triggers a configuration reload across all shell components.

These files demonstrate how Omarchy separates presentation logic from configuration data, allowing you to customize the lock screen without modifying QML code.

## Summary

- Omarchy lock screen themes rely on a [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) file inside your theme directory that merges with base theme settings.
- The Quickshell lock service at `shell/plugins/lock/Service.qml` handles configuration loading and merging at lock time.
- You only need to specify override values—wallpaper paths, color hex codes, or boolean flags—while inheriting fonts and icons from the main theme.
- Activate custom themes using `omarchy-theme-set` and test with `loginctl lock-session`.

## Frequently Asked Questions

### Where does Omarchy look for the lock screen configuration file?

Omarchy searches for [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) inside the currently active theme directory, typically located at `~/.config/omarchy/themes/<theme-name>/` or the system-wide installation path. The `Service.qml` component specifically checks this path during the lock initialization sequence.

### Can I use a video background instead of a static image?

Yes. While the `wallpaper` key accepts static image paths, you can specify a `video` key in [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) with an absolute path to a video file. The Quickshell media layer in `LockView.qml` handles video decoding and rendering when this key is present.

### Do I need to redefine all colors in shell.lock.toml?

No. You only need to define values you want to override. The merge logic in the lock service uses fallback values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) if a specific key is absent from [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml), allowing minimal configuration files that change just one or two properties.

### Why is my shell.lock.toml being ignored?

The most common causes are filename mismatches—the file must be named exactly [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml)—and path errors. Ensure the file resides directly inside the theme root, not in a subdirectory, and verify that `omarchy-theme-set` has activated the correct theme before locking.