quickshell.org

Quickshell is for people who want to build their own desktop shell components — status bars, widgets, lockscreens, and similar pieces — rather than accept what a desktop environment ships with. It is a toolkit built on QtQuick, configured in QML, and designed to run alongside a Wayland compositor or window manager. If you are comfortable editing a config file and want live-updating, fully custom desktop elements, it fits. If you want a ready-made desktop you install and never touch, it does not.

What you can build

The site describes Quickshell as "building blocks for your desktop," a toolkit for constructing desktop components. The concrete categories it names:

• Status bars — the panel that typically holds workspaces, clock, system tray, and indicators.
• Widgets — small standalone desktop elements.
• Lockscreens — the screen shown when the session is locked.
• Other desktop components — the site's phrasing is open-ended, and it says it can be used to "build a complete desktop environment" when combined with a compositor or window manager.

The gallery on the site shows real configurations from named authors (soramane, end_4, outfoxxed, pfaj and bdebiase, flicko, vaxry), some with install links and some with source code. That range is a useful signal: people are shipping complete, distinct shells with it, not just toy examples.

Who it is actually for

Two groups get value here:

People assembling a personal desktop. You already run a Wayland compositor or window manager and want the shell layer on top to match your setup instead of fighting a fixed panel. Quickshell supplies the components; you decide the layout and behavior.

Developers building reusable desktop pieces. Because configuration is code in QML, components can be structured, reused, and extended. The site notes LSP support, so editor tooling works while you write.

The common requirement for both is willingness to work in QML. The site calls QML "a simple language designed for creating flexible user interfaces" — simple relative to general-purpose UI frameworks, but still a language you configure in, not a settings panel you click through.

What working in it looks like

Configuration is QML, and the site's example is a FloatingWindow containing a Timer that flips a custom boolean property every 500 ms, with the window color bound to that property:

FloatingWindow {
    Timer {
        id: timer
        property bool invert: false
        running: true; repeat: true
        interval: 500 // ms
        onTriggered: timer.invert = !timer.invert
    }
    color: timer.invert ? "purple" : "green"
}

Two things stand out for anyone deciding whether to invest time:

• Property binding is the core mechanic. color is not set once; it is bound to timer.invert, so it re-evaluates whenever that value changes. This is how you make a bar react to state without writing update loops.
• Changes load as soon as they are saved. The site states Quickshell reloads on save, so the edit-run cycle is immediate. For shell work, where you are tuning spacing, colors, and layout constantly, that shortens iteration a lot.

Integrations and current state

The site says Quickshell ships with "a large set of integrations, with new ones arriving all the time" — useful if your shell needs to talk to system services, but the site does not enumerate them here, so check the documentation for the specific integration you need before committing.

Version 0.3.1 is the current release noted on the page (dated 2026-08-20). The project is led by outfoxxed, with website work by xanazf and contributions from others.

How to decide

The practical next step is to read the documentation and look at the example configurations in the gallery — especially any with source code — to judge whether the QML approach matches how you want to work. The site does not state pricing or login requirements, so treat availability and access terms as something to confirm on the site itself.

Quickshell's official site (quickshell.org) is the starting point: it links directly to Install and Documentation, and its homepage showcases several community-made configurations, some with install or source links. If you want to see what Quickshell can look like before writing your own setup, those examples are the fastest way in. The current release listed on the site is Quickshell 0.3.1 (dated 2026-08-20), and a Changelog link is available for tracking version changes.

Official Resources on quickshell.org

The homepage is short and functional. From it you can reach:

• Install — installation instructions for getting Quickshell onto your system.
• Documentation — the reference material for configuring Quickshell in QML.
• Changelog — release history, including the 0.3.1 release noted on the page.

Quickshell describes itself as "a fully user customizable desktop shell" and "building blocks for your desktop" — a toolkit for building status bars, widgets, lockscreens, and other desktop components using QtQuick. It's designed to be used alongside your Wayland compositor or window manager to build a complete desktop environment. That framing matters for reading the docs: you're not configuring a finished shell, you're assembling one.

Example Configurations Shown on the Site

The homepage lists configurations credited to community members. Some entries include a link to install or to source code, which makes them usable as starting points rather than just screenshots:

If you learn best by reading working code, the entries with source code links are the most useful — outfoxxed is credited as Lead Developer, so that configuration is worth reading as a reference for idiomatic structure. The install links let you try someone else's setup directly before modifying anything.

What the Documentation Covers

Quickshell is configured in QML, described on the site as "a simple language designed for creating flexible user interfaces," with LSP support for editor tooling. Two properties of the workflow are worth knowing before you dig in:

• Live reload — Quickshell loads changes as soon as they're saved, so you can iterate as fast as you can type. You don't restart anything to see a color or layout change.
• QML as the configuration language — the docs assume you're writing QML, not a bespoke config format.

The site's own example shows the shape of it: a FloatingWindow containing a Timer with a custom invert property, where the window's color switches between "purple" and "green" based on that property. That's the core pattern — QML objects, properties, and bindings.

Practical Path

1. Start at quickshell.org and open Install to get it running.
2. Read Documentation for the QML API and available integrations — the site notes "a large set of integrations, with new ones arriving all the time."
3. Pick an example configuration with a source code link to study, or an install link to try one immediately.
4. Check the Changelog when something behaves differently than an older guide suggests, since the project is actively released (0.3.1 as of 2026-08-20).

One caveat: the homepage lists example authors and links but doesn't describe what each configuration does, so you'll need to open them to judge fit. The site also doesn't state pricing or licensing terms on the page — check the repository or documentation if that matters for your use.

Quickshell is a toolkit for building desktop components — status bars, widgets, lockscreens, and similar — using QtQuick. You install it from the project's Install page, then write your configuration in QML. The workflow is unusually fast to iterate on because Quickshell reloads your changes as soon as you save them, so you can edit and see the result without restarting anything.

This guide covers what you need before starting, how to get Quickshell onto your system, how to write and test a first configuration, and where the common sticking points are.

What you need before you start

Quickshell is designed to run alongside a Wayland compositor or window manager, so you should already have one set up and working. It is not a compositor itself — it builds the desktop components that sit on top of one.

You will also want to be comfortable reading and editing plain text configuration files. No prior QML experience is strictly required, but the configuration language is QML, so some familiarity with declarative UI syntax helps.

Installing Quickshell

The project points to two primary entry points on its site: Install and Documentation. Start with Install — that page carries the current, authoritative instructions for your platform, which is the right place to check because packaging details change between releases.

The site notes that Quickshell 0.3.1 has been released, so confirm which version you are pulling and match your configuration to it if you run into syntax or API differences.

A general sequence that works for most Linux desktop tooling:

1. Open the Install page from the Quickshell site.
2. Follow the instructions for your distribution or build method.
3. Verify the install by checking that the Quickshell binary or library is available on your system.
4. Move on to configuration only after the install step completes cleanly.

If your distribution's package is older than the current release, the Install page is where you will find the alternative build or source instructions.

Writing your first configuration

Quickshell is configured in QML. The site's own example is a good starting template because it demonstrates the two things you will use constantly: objects with IDs, and properties that drive other properties.

// a standard desktop window
FloatingWindow {
  Timer {
    // assign an id to the object, which can be
    // used to reference it
    id: timer
    property bool invert: false // a custom property
    // change the value of invert every half second
    running: true; repeat: true
    interval: 500 // ms
    onTriggered: timer.invert = !timer.invert
  }
  // change the window's color when timer.invert changes
  color: timer.invert ? "purple" : "green"
}

Reading this example tells you the core mechanics:

• FloatingWindow is a desktop window component.
• Timer is a child object that fires repeatedly.
• id: timer gives the object a name so other properties can reference it.
• property bool invert: false declares a custom property.
• color: timer.invert ? "purple" : "green" binds the window color to that property, so the color changes automatically when invert flips.

That last line is the key idea in QML: you declare relationships between values rather than writing update code. When timer.invert changes, anything bound to it re-evaluates.

Seeing your changes in real time

Quickshell loads changes as soon as they are saved. This means your edit-test loop is: change the file, save it, and watch the running desktop component update. You do not need to restart Quickshell or your compositor between edits.

This matters most when you are tuning layout, spacing, or colors, where you want to nudge a value and immediately judge the result.

Editor support

Quickshell has LSP support, so if your editor can talk to a language server you can get completion and diagnostics for QML while writing your configuration. Setting this up is worth doing before a configuration grows large.

Learning from existing configurations

The site lists several community configurations you can study or install, which is often faster than starting from an empty file:

Configurations marked with source code are the most useful for learning, because you can read the QML directly and see how the author structured their components. Those marked with install are quicker to try if you just want a working setup to modify.

Common sticking points

Editing without saving. The live reload triggers on save, not on keystroke. If nothing changes, check that your editor actually wrote the file.

Referencing an object before it has an id. The example assigns id: timer specifically so the color binding can reach it. If you bind to a name that does not exist, the binding will not resolve.

Assuming a configuration from an older release still applies. With 0.3.1 current, a configuration written against an earlier version may need adjustment. Check the Documentation when something behaves unexpectedly.

Treating Quickshell as a compositor. It builds desktop components that run alongside your Wayland compositor or window manager. If you have no compositor running, there is nothing for it to attach to.

Where to go next

Once a minimal FloatingWindow renders and responds to a property change, you have the full loop working: install, configure in QML, save, observe. From there, the Documentation is the reference for the integrations Quickshell ships with, and the community configurations above are the practical examples for building a complete desktop environment out of status bars, widgets, and lockscreens.

Quickshell is a toolkit for building desktop components — status bars, widgets, lockscreens, and similar elements — using QtQuick. It is configured in QML and runs alongside a Wayland compositor or window manager, so it fits into an existing setup rather than replacing it. If you want a desktop shell you can shape yourself, down to individual components, Quickshell is aimed at that use case.

What it does

The project describes itself as "building blocks for your desktop." Instead of shipping one fixed shell, it gives you the pieces to assemble your own:

• Status bars — top or bottom panels with the modules you choose
• Widgets — small desktop components such as clocks, indicators, or custom displays
• Lockscreens — session lock surfaces built with the same toolkit
• Other desktop components — anything expressible as a QtQuick surface

Because it works alongside a Wayland compositor or window manager, you can adopt it incrementally. A single widget is a valid starting point; a full desktop environment is the other end of the range.

How configuration works

Quickshell is configured in QML, a declarative language designed for flexible user interfaces. The project highlights two practical consequences:

Live reload. Changes are loaded as soon as they are saved, so you can iterate without restarting anything. This matters most when tuning layout or colors, where the feedback loop is otherwise the slow part.

LSP support. Language server tooling works with QML here, which means completion and diagnostics while you write.

A minimal example from the project's own documentation shows the shape of it — a floating window whose color flips on a timer:

FloatingWindow {
  Timer {
    id: timer
    property bool invert: false
    running: true; repeat: true
    interval: 500 // ms
    onTriggered: timer.invert = !timer.invert
  }
  color: timer.invert ? "purple" : "green"
}

The pattern generalizes: declare an object, give it properties, and bind other values to those properties. The window color is not set imperatively — it is bound to timer.invert, so it updates whenever that value changes.

Integrations

Quickshell ships with a large set of integrations and adds more over time. The project does not enumerate them on its landing page, so check the documentation for the current list before assuming a specific service or protocol is covered.

Who it is for

Quickshell suits you if:

• You already run a Wayland compositor or window manager and want to add or replace desktop components
• You are comfortable writing QML, or willing to learn it
• You want real-time feedback while editing your shell

It is a poorer fit if you want a prebuilt, ready-to-run desktop environment with no configuration, or if you are not on Wayland.

Getting started

The project points to three entry points:

The landing page also links several community configurations by name — soramane, end_4, outfoxxed, pfaj and bdebiase, flicko, and vaxry — with install or source links where available. Reading an existing configuration is often faster than starting from an empty file, since it shows how real layouts are structured.

The current release noted on the site is Quickshell 0.3.1 (dated 2026-08-20).

Quickshell is a toolkit for building desktop components — status bars, widgets, lockscreens, and similar — using QtQuick/QML rather than a configuration script or a fixed plugin format. It is designed to run alongside your Wayland compositor or window manager, not to replace it. The distinction matters most if you want to author your own desktop components in a real UI language instead of assembling them from pre-built modules or editing a config file.

The core differences

Configuration is code, not a config file

Most desktop shell tools ask you to edit a text configuration file: you set options, choose modules, and the tool renders a fixed set of components. Quickshell instead has you write QML — a declarative language designed for building flexible user interfaces. The site's own example is a FloatingWindow containing a Timer that flips a custom invert property every 500 ms and changes the window color between purple and green based on that property.

That is a meaningful shift in kind, not degree. You are not selecting from a menu of widgets; you are defining objects, properties, and bindings. Anything the toolkit exposes can be composed into something new.

Live reload as a workflow, not a feature

Quickshell loads changes as soon as they are saved. The site frames this as iterating "as fast as you can type." For anyone who has configured a shell by editing a file and restarting the process to see the result, this changes the loop: edit, save, observe. It also means experimentation is cheap, which suits a toolkit where you are writing layout and logic rather than toggling options.

It complements your compositor rather than replacing it

Quickshell is explicitly positioned to be used alongside your Wayland compositor or window manager to build a complete desktop environment. It is not a compositor, and it does not take over window management. If you already have a compositor you like, Quickshell sits on top of it and supplies the desktop components.

Integrations are broad and expanding

The site states Quickshell ships with a large set of integrations, with new ones arriving continuously. This is the part of the comparison that is hardest to pin down from the homepage alone — the specific integrations are not enumerated there — so if a particular service or protocol matters to you, check the documentation rather than assuming coverage.

Where the trade-off lands

Who this suits

Choose Quickshell if you want to build desktop components rather than configure them, you are comfortable (or willing to learn) QML, and you already have a Wayland compositor or window manager you intend to keep. The live-reload behavior rewards people who iterate by trying things.

Look elsewhere if you want a shell that works out of the box with minimal authoring, if you are not on Wayland, or if you need a specific integration that you cannot confirm exists. The homepage shows example configurations by several contributors (soramane, end_4, outfoxxed, pfaj and bdebiase, flicko, vaxry) with install or source links — those are the fastest way to judge whether the result matches what you want before committing to writing your own.

Getting oriented

The site points to three entry points: Install, Documentation, and More information. Quickshell 0.3.1 was released 2026-08-20, so check the changelog for what is current. Start from an existing configuration if you want a working baseline, then modify it — the save-and-reload loop makes that a low-risk way to learn the QML structure.