3 +How to get `quickshell` (`qs`) on your system. Picked from the live install page at `https://quickshell.org/docs/<version>/guide/install-setup/`. Re-check that page when bumping versions; package availability changes.
7 +| Distro | Package | Notes |
9 +| **Arch (official)** | `quickshell` | In `[extra]`. Pin for stability. |
10 +| **Arch (AUR)** | `quickshell-git` | Tracks master. May break on Qt updates; quickshell warns. |
11 +| **NixOS** | `nixpkgs` `quickshell` | Stable. |
12 +| **Nix (flake)** | flake input | `quickshell.packages.<system>.default` |
13 +| **Debian unstable/testing** | `quickshell` | |
14 +| **Fedora Rawhide** | `quickshell` | |
15 +| **Fedora COPR** | `errornointernet/quickshell` (release) / `quickshell-git` (master) | |
16 +| **Ubuntu** | `ppa:avengemedia/danklinux` → `quickshell` or `quickshell-git` | |
17 +| **openSUSE** | OBS `home:AvengeMedia:danklinux` → `quickshell` or `quickshell-git` | |
18 +| **Gentoo** | `guru` overlay → `gui-apps/quickshell` | |
19 +| **Guix** | `(gnu packages wm)` → `quickshell` | |
26 + nixpkgs.url = "nixpkgs/nixos-unstable";
28 + url = "git+https://git.outfoxxed.me/quickshell/quickshell";
29 + # THIS IS IMPORTANT: mismatched system deps lead to crashes.
30 + inputs.nixpkgs.follows = "nixpkgs";
39 +environment.systemPackages = [ inputs.quickshell.packages.<system>.default ];
40 +# or with extra QML modules:
41 +inputs.quickshell.packages.<system>.default.withModules [ ./my-extra-modules ]
44 +Add `?ref=<tag>` to the URL to pin a tagged release.
48 +See `https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md`.
50 +Common path: install Qt6 dev packages + ninja, then `cmake -B build -G Ninja && ninja -C build`.
52 +##
Runtime dependencies (for the package maintainer or source build) 54 +Quickshell links against:
56 +- Qt6 (`qt6-base`, `qt6-declarative`, `qt6-quickcontrols2`).
57 +- Wayland client libs (`libwayland-client`).
58 +- For pipewire: `libpipewire`.
59 +- For screencopy Vulkan: `vulkan-headers` (build-time), `vulkan-Loader` (runtime).
60 +- For screencopy non-Vulkan: none extra.
61 +- For polkit agent: `glib`, `polkit`.
62 +- `libdrm` is now an unconditional direct dep (since v0.3.0).
63 +- Wayland/WlrLayershell features require a wlroots-based compositor (Hyprland, Sway, etc.) for full functionality. X11 and Niri work but with feature gaps.
65 +##
Optional runtime Qt modules 67 +These are bundled in most distros but worth checking on slim Arch installs:
69 +- `qtsvg` — SVG images.
70 +- `qtimageformats` — WEBP, TIFF, etc.
71 +- `qtmultimedia` — audio/video playback.
72 +- `qt5compat` — extra visual effects (MultiEffect, gaussian blur). `MultiEffect` is usually preferred where available.
74 +##
Verifying the install 84 +##
Editor setup (LSP) 86 +Touch the qmlls marker to enable completions:
89 +touch ~/.config/quickshell/
<name
>/.qmlls.ini
92 +Quickshell overwrites it with a managed qmlls config. **Gitignore it** (its content depends on local paths).
94 +Known qmlls issues to be aware of:
96 +- Doesn't work well when a file contains types from multiple qs.* modules.
97 +- May report false-positive undefined-symbol errors after a fresh `qs` install until you restart your editor.
103 +| `qs: error while loading shared libraries: libQt6…` | Install Qt6 runtime. |
104 +| Panel doesn't appear | Compositor must be Wayland + wlroots-based; check `echo $WAYLAND_DISPLAY`. |
105 +| Panel appears but is opaque white | You set `color: "transparent"` and a child has `border` without `border.width: 0` — QTBUG-137166. Add `border.width: 0`. |
106 +| `quickshell-git` AUR rebuilds every Qt update | Quickshell will warn; just reinstall. |
107 +| IPC `qs ipc call` says "no such target" | The target is the string you set on `IpcHandler { target: ... }`, not the config name. |
108 +| `qmlls` complains about every Quickshell symbol | `.qmlls.ini` is missing or stale; delete and re-touch. |