Quickshell on Omarchy

Quickshell on Omarchy

Quickshell is a free (LGPL-3.0) QtQuick/QML toolkit for building desktop shells on Wayland — bars, widgets, lock screens, notifications, menus — and it’s what Omarchy’s own shell is built on, so it’s already the runtime behind your bar whether you knew it or not.

TL;DR

omarchy pkg add quickshell

Takes under a minute (2.2 MB download, 6.4 MB installed, plus the Qt6 stack it depends on). This is a toolkit, not an app — there’s no window to open and no launcher icon. You write your shell in QML (a shell.qml file), and quickshell runs it. If you just want to use Omarchy, you already have it: the Omarchy bar, menus, and widgets are quickshell QML running right now.

Getting started (5 minutes)

1. Install and confirm the runtime.

omarchy pkg add quickshell, then quickshell --version in a terminal. If the Omarchy shell is running, you’re already looking at quickshell’s output — the bar is QML.

2. Run the smallest possible shell.

From the official docs’ introduction, this is the whole “hello world” — a clock bar across the top of every screen:

// shell.qml
import Quickshell
import Quickshell.Io
import QtQuick

Scope {
  id: root
  property string time
  Variants {
    model: Quickshell.screens
    PanelWindow {
      required property var modelData
      screen: modelData
      anchors { top: true; left: true; right: true }
      implicitHeight: 30
      Text {
        anchors.centerIn: parent
        text: root.time
      }
    }
  }
  Process {
    id: dateProc
    command: ["date"]
    running: true
    stdout: StdioCollector { onStreamFinished: root.time = this.text }
  }
  Timer {
    interval: 1000; running: true; repeat: true
    onTriggered: dateProc.running = true
  }
}

Save it as shell.qml in a directory and run quickshell there (confirm the exact invocation on-machine — the docs’ intro covers the config layout). You get a 30px bar with the time, on every monitor. That’s the whole mental model: QML describes the UI, quickshell gives you Wayland superpowers (PanelWindow, per-screen variants, system processes, IPC) that plain Qt can’t.

3. The three things everyone needs to know:

• Grow by splitting files. One giant shell.qml gets unmanageable fast. The docs’ pattern: move the bar into Bar.qml, the clock into ClockWidget.qml — any QML file starting with an uppercase letter becomes a reusable type you reference by name (Bar {}). Subfolders come in via import statements. This is how the Omarchy shell itself is organized, and how community plugin authors (like the meeting-recorder bar widget) ship theirs.
• It’s pre-1.0 and it says so. From the official install docs: “Quickshell is still in a somewhat early stage of development. There will be breaking changes before 1.0, however a migration guide will be provided.” Concretely: pin your shell to the quickshell version it was written against, read the changelog before updating, and prefer the Omarchy-packaged quickshell (pinned commit) over -git for anything you don’t want to babysit.
• Optional Qt modules unlock features. Depending on your distro packaging you may want qtsvg (SVG icons — bundled with most packages), qtimageformats (WEBP and friends), qtmultimedia (video/audio in your shell), and qt5compat (extra effects, notably gaussian blur — though the docs note MultiEffect is usually preferable). If your shell’s SVGs render as blank boxes or blur does nothing, a missing module is the first suspect.

4. Where its config lives.

Your shells, your choice — quickshell runs whatever config directory you point it at. Omarchy’s own shell QML and its plugins live under the Omarchy config tree (confirm exact paths on-machine: the shell plugins directory is ~/.config/omarchy/plugins/, where e.g. the meeting-recorder widget links in as jankeesvw.meeting-recorder). Plugin lifecycle commands from the Omarchy side: omarchy-shell shell rescanPlugins, omarchy-shell shell listPlugins, omarchy plugin enable <name> --section right.

quickshell vs quickshell-git — pick one.

The quickshell package is a pinned, stable snapshot: version 0.3.2.r7.g2b4501a means “7 commits past the v0.3.2 tag, at commit 2b4501a,” built by Omarchy with their own patch and crash reporter off. quickshell-git tracks the latest master commit — newer features, newer breakage. They declare a package conflict, so installing one removes the other. Rule of thumb: if you’re writing a shell you want to keep working, take the pinned quickshell; if you’re developing on quickshell or need a fix that landed yesterday, take -git and accept the churn.

Common issues & fixes

Your shell (or a community shell like Caelestia) crashes on login; launching it manually in a terminal works

Real report from the Arch forums (“Quickshell crash on login”): a user with the Caelestia shell saw quickshell crash every login on a fresh Arch install, but caelestia shell run by hand in a terminal worked fine — and the same setup didn’t crash on their laptop, suggesting environment/hardware-specific causes. Quickshell writes crash logs to its crash folder — read those first (the log in that thread included full system info). Usual suspects: the shell starting before the Wayland session is fully up (add a delay or order it after the compositor in your autostart), or mismatched system libraries. On Omarchy specifically, stick to the packaged quickshell built against Omarchy’s Qt rather than mixing in a -git or foreign build.

Crashes or weird behavior after a system update, especially with Nix/home-manager setups

Fix: From the official docs’ Nix section, verbatim: “Mismatched system dependencies will lead to crashes and other issues.” Quickshell is sensitive to the exact Qt and system libraries it was built against. The Omarchy package handles this by building quickshell itself (with DISTRIBUTOR='Omarchy') against the repo’s Qt — so the fix is the same as the cause: install quickshell from the same package set as the rest of your system, don’t hand-mix builds, and after a big Qt update, make sure quickshell was rebuilt too (a repo update handles this; a manual build doesn’t).

Your QML worked last month and broke after updating quickshell

Fix: Expected, not a bug — “there will be breaking changes before 1.0, however a migration guide will be provided” (official docs). Check the release notes/migration guide for the version you jumped to, and consider whether you actually want the rolling quickshell-git or the pinned quickshell package. If you maintain a shell others use, state the supported quickshell version in your README.

SVG icons show as blank, WEBP images don’t load, video elements stay black, or gaussian blur has no effect

Fix: Missing optional Qt modules. The official install docs list exactly these: qtsvg for SVG (usually bundled), qtimageformats for WEBP and less common formats, qtmultimedia for video/audio, qt5compat for extra effects like gaussian blur. Install the missing module for your distro and restart the shell. (Check what’s already installed before assuming — Omarchy’s packaging may bundle some.)

You installed both quickshell and quickshell-git and pacman complains

Fix: They conflict by design (conflicts=(quickshell-git) in the Omarchy PKGBUILD) — you can only have one. omarchy pkg remove the one you don’t want, then install the other. If a community shell’s install script pulls in -git as a dependency, decide consciously: -git for latest-master features, quickshell for the stable pinned build.

Pairs well with / If you hate this, try

Pairs well with

• Hyprland (Omarchy’s compositor — quickshell is the Wayland-shell counterpart to it). The Omarchy plugin system (~/.config/omarchy/plugins/) — the sanctioned way to add quickshell widgets to the Omarchy bar without forking the whole shell. Any QML knowledge you have from Qt carries over directly.

If you hate this, try

• AGS (Aylur’s GTK Shell) — the GTK/GJS alternative with a big widget ecosystem, if you think in JavaScript rather than QML. eww (ElKowars wacky widgets) — lighter, simpler, great for a couple of custom widgets without committing to a full shell toolkit. nwg-shell — a more batteries-included Wayland shell if you want customization without writing QML. None of these run Omarchy’s shell, though — on Omarchy, quickshell is the home team.

Comparison: Wayland shell toolkits

Verdict: On Omarchy, learn quickshell — it’s what your bar already runs, and a pinned package means your config won’t rot monthly. Reach for -git only if you’re chasing upstream features; reach for AGS/eww if you refuse QML on principle.