QUICKSHELL(1)

📦 version 0.3.0, in ubuntu stonking

💖 QUICKSHELL 💖

okay bestie, so this is the manual page for quickshell — it lives in section 1 of the manual (aka User Commands), and it is genuinely one of the most fun little toolkits out there. let's get into it 🫶

✨ NAME ✨

quickshell — a flexible QtQuick-based desktop shell toolkit 💅

🌸 SYNOPSIS 🌸

quickshell [OPTIONS] [SUBCOMMAND]

🦋 DESCRIPTION 🦋

so basically, Quickshell is a toolkit for building status bars, widgets, lockscreens, and other desktop components using Qt6 and QtQuick. she supports both Wayland and X11, no cap, and comes with integrations for PipeWire, MPRIS, system tray, PAM, Bluetooth, plus compositor-specific features for Hyprland and Sway/i3. like?? the range?? 🌈

configuration is done declaratively in QML, with live hot-reloading — meaning you change a thing and it just updates, no restart arc required. iconic behavior fr fr ✨

👑 OPTIONS 👑

  • -h, --help — prints the help message and then dips. bye bestie 💨
  • -V, --version — prints quickshell's version and exits. show-off behavior, we love it
  • -n, --no-duplicate — if another instance of the same config is already running, exit immediately. no duplicates allowed, this is a monogamy household 🙈
  • -d, --daemonize — detaches from the controlling terminal. she's independent now 🦋

🎀 Config Selection 🎀

Quickshell finds configs as named directories under each XDG config directory, like this:

<xdg dir>/quickshell/<config name>/shell.qml

and if <xdg dir>/quickshell/shell.qml exists? that gets registered as the 'default' configuration, and no subdirectories will be considered at all. periodt. and if you don't pass --config, then 'default' is just assumed (main character energy, honestly).

alternatively, you can pick a config by path with --path 💫

  • -p, --path TEXT — path to a QML file or config folder. this one excludes --config and --manifest. environment variable: QS_CONFIG_PATH. 🍓
  • -c, --config TEXT — name of a quickshell configuration to run. excludes --path. environment variable: QS_CONFIG_NAME.
  • -m, --manifest TEXT — [DEPRECATED] ⚠️ path to a quickshell manifest. excludes --path. environment variable: QS_MANIFEST.

🌸 Logging 🌸

  • --no-color — turns off colored logging. you can also kill the color by setting the NO_COLOR environment variable.
  • --log-times — stamps a timestamp on every single log message ⏰
  • --log-rules TEXT — the log rules to apply, formatted like QT_LOGGING_RULES.
  • -v, --verbose — cranks up log verbosity. -v shows INFO level internal logs, and -vv shows DEBUG level internal logs. the more v's, the more she tells you 🗣️

💜 Debugging 💜

  • --debug PORT — opens the given port (0-65535) for a QML debugger connection 🔍
  • --waitfordebug — waits for a QML debugger to connect before executing the configuration. requires --debug. she's patient but she needs the port, okay??

✨ Subcommand Filtering ✨

subcommands that operate on running instances accept this filter:

  • --any-display — don't restrict the match to instances launched on the current display. so she'll look everywhere 👀

🌈 SUBCOMMANDS 🌈

  • log — print quickshell logs 📜
  • list — list running quickshell instances 📋
  • kill — kill quickshell instances 🔪 (dramatic but necessary)
  • ipc — communicate with other Quickshell instances. this includes per-handler listener subcommands for IpcHandler signals registered by the running shell 📡
  • msg — [DEPRECATED] ⚠️ moved to ipc call.

💅 EXAMPLES 💅

Run the default configuration:

qs

Run a named configuration:

qs -c myconfig

Run from a specific path:

qs -p ~/myshell

Run a specific QML file:

qs -p ~/myshell/randomfile.qml

🫶 ENVIRONMENT 🫶

  • QS_CONFIG_PATH — path to a QML file or config folder.
  • QS_CONFIG_NAME — name of a quickshell configuration to run.
  • NO_COLOR — if set to a non-empty value, disables colored logging. (yes, empty doesn't count. she's picky.) 🙈

⭐ SEE ALSO ⭐

qs(1) — go read that one too, bestie, iykyk

🎀 AUTHORS 🎀

Quickshell was written by outfoxxed <outfoxxed@outfoxxed.me>. thank you for your service, king 👑

okay that's the whole thing!! this page is from quickshell version 0.3.0, dated 2026-05-04 — so you're reading a certified fresh release, no cap. now go build something gorgeous with it, bestie 🦋💖✨

📦 where this page comes from