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

You create a custom Omarchy lock screen by adding a 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 inside the currently active theme folder—such as 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.

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 takes precedence over the same key in the base theme configuration.
• Fallback behavior: Missing keys automatically inherit values from 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:

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

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

The file name must match exactly—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 and define your lock-screen-specific properties. You can set static wallpapers, video backgrounds, color overrides, and boolean flags for visual effects:

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:

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:

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:

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, 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: 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 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 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 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 if a specific key is absent from 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—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.

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