# QuickShell Quickshell is a toolkit for building your own desktop shell on [[Linux]]. Status bar, notification popups, lock screen, app launcher, media controls, system tray. You write them yourself, in QML, and Quickshell runs them as one process on top of your compositor. Most people never think about this because their desktop environment already decided for them. If you run GNOME or KDE, the shell is part of the deal. But the moment you go tiling, on Hyprland, Sway, or a distro like [[Omarchy]] that ships one for you, the shell stops being a given. You assemble it. And that's where the trouble starts. ## Why this exists The usual way to build a tiling desktop is to bolt separate programs together. Waybar for the bar. Mako or Dunst for notifications. Wofi or Rofi for the launcher. Swaylock for the lock screen. Each one has its own config format, its own theme file, its own idea of what a color is. Each one is a separate process that knows nothing about the others. It works. I ran that setup for a long time. But it has a real cost: you can't make the bar react to something the notification daemon knows, because they don't talk. Want the volume popup to appear next to the volume widget you clicked? Good luck. You end up writing shell scripts that shove state through IPC sockets, and every theme change means editing five files in four different syntaxes. Quickshell takes the opposite position. One process owns all of it. The bar, the popups, the launcher, the lock screen. They share state because they're the same program. That's the actual argument, and it's a good one. ## How you configure it You write QML. Not a config file that pretends to be a config file, not JSON with CSS bolted on. Actual declarative UI code, the same language Qt uses for QtQuick. ```qml FloatingWindow { Timer { running: true interval: 1000 repeat: true onTriggered: parent.color = parent.color === "red" ? "blue" : "red" } } ``` Two things make this pleasant. First, hot reloading: save the file and the shell updates. No restart, no logout, no "did it pick that up?". Second, LSP support, so you get completion and error checking while you write. QML is reactive by design. A property that depends on another property updates itself when that other property changes. For UI work this is exactly the right model, and it's why the whole thing feels less like configuring software and more like building it. Configs live as a `shell.qml` entry point plus whatever you split out from there. ## What's already in the box You're not writing a Wayland protocol client from scratch. Quickshell ships modules for the things a shell actually needs: - **Wayland**: layer shell (how you pin a bar to a screen edge), session lock, toplevel management - **Compositors**: Hyprland and i3/Sway integration, so you can read and drive workspaces - **Audio and media**: PipeWire, MPRIS playback control - **System services**: notifications, system tray, Bluetooth, networking - **Authentication**: PAM and Polkit, which is what makes a real lock screen possible X11 is supported too, though Wayland is clearly where the attention goes. ## The trade-offs I'm not going to pretend this is a free lunch. **You write real code.** Waybar is configured in ten minutes. Quickshell is not configured, it's programmed. If you want a bar by lunchtime, this is the wrong tool. If you want a desktop that behaves exactly the way you think it should, it's the right one. **QML layout is its own thing.** The docs say this explicitly: laying out elements in QML works quite differently from CSS. Read the "Item Size and Position" page before you build anything, or you'll spend an afternoon fighting positioning you thought you understood. **It pulls in Qt6.** The full QtQuick runtime sits underneath. Baseline memory is heavier than a minimal Waybar. The counter-argument is that you're replacing four or five daemons with one process, so the total often comes out ahead. Measure it on your own machine rather than trusting either side of that argument. **It's pre-1.0.** Version 0.3.1 as of August 2026. Things move. If you build a large config, expect to fix it occasionally. The community answer to the first problem is prebuilt configs. end-4's dots-hyprland is the reference example: a complete Quickshell setup you can install and then modify, rather than starting from an empty file. That's how I'd suggest approaching it. Start from something that works, change one widget, see what happens. ## Where it actually lives The GitHub repository is a mirror. Real development happens on outfoxxed's own Forgejo instance at `git.outfoxxed.me`. Issues and pull requests belong there, not on GitHub. Licensed under the GNU LGPL 3.0. ## Compared to the alternatives | Tool | Language | Scope | | --- | --- | --- | | Quickshell | QML (Qt6) | Full shell: bar, popups, launcher, lock screen | | AGS | TypeScript (GTK) | Full shell, same idea, different toolkit | | Eww | S-expressions (Rust) | Standalone widgets, works under X11 WMs too | | Waybar | JSON + CSS | A bar, and only a bar | The real deciding factor is which language you want to live in. AGS does the same job with TypeScript and GTK. If you already write TypeScript daily, that may matter more than any technical difference between the two. ## My take I run [[Omarchy]], which means Hyprland, which means the shell question is mine to answer. Quickshell is the most convincing answer I've seen so far, because it fixes the actual problem instead of making the workaround prettier. Separate daemons that can't talk to each other is the problem. One reactive process is the fix. The cost is that you have to build it. For most people that's disqualifying, and that's fine. For anyone who already treats their setup as something worth investing in, it's the point. ## References - Official website: https://quickshell.org/ - Documentation: https://quickshell.org/docs/ - Source code (primary): https://git.outfoxxed.me/quickshell/quickshell - Source code (GitHub mirror): https://github.com/quickshell-mirror/quickshell - Examples: https://git.outfoxxed.me/quickshell/quickshell-examples ## Related - [[Omarchy]] - [[Arch Linux]] - [[Linux]] - [[Open Source]]