How can we help?

Arch Linux and Hyprland. Lucid uses Hyprland-specific APIs for workspaces and window management, so it will not work on Sway, niri, GNOME, KDE or any other compositor. The installer relies on pacman and the AUR, so other distributions aren't supported either.

The shell itself only strictly needs quickshell, qt6-5compat, qt6-declarative and qt6-multimedia. Everything else backs one feature each, and the installer offers to pull it all in.

$ git clone https://github.com/Sn3akyy1/lucid.git
$ cd lucid
$ ./install.sh

Then run hyprctl reload, or log out and back in to pick up the autostart. On first run, set a wallpaper from Settings → General. That generates your palette.

Pull and run the installer again. Your settings, pinned apps, reminders, Shazam history and API keys are carried into the new install, and the old one is kept as ~/.config/quickshell.backup-<timestamp>.

$ git pull
$ ./install.sh

You don't have to watch for releases: Lucid checks once a day and tells you once per version, in a notification.

Not without asking, and never without a backup. An existing Hyprland config is backed up and you are asked first. An existing matugen/config.toml is appended to, never replaced. Your old ~/.config/quickshell is moved aside with a timestamp.

To keep things entirely your own, pass --no-hypr (keeps your Hyprland config), --no-look (leaves kitty, starship, your shell rc files, VSCode and GTK alone) or --no-theming (leaves matugen and ~/.config/lucid alone).

The update check asks api.github.com/repos/Sn3akyy1/lucid/releases/latest once a day. It is a plain curl that carries nothing about you or your machine, and Settings → About turns it off.

The weather comes from Open-Meteo, one forecast shared by the bar, the lock screen and the widget. With Auto-detect location on, your position is looked up from your network connection every few hours; leave it off and name a town yourself.

GIF search talks to Giphy or Tenor, and only if you gave it a key.

Run ./uninstall.sh from the repo. It moves ~/.config/quickshell aside rather than deleting it, leaves installed packages alone, and prints everything else it left in place, each with a timestamped backup beside it so you can undo it by hand.

Check the log for QML errors, and confirm you are on Hyprland. Lucid needs its Wayland protocols.

$ qs log

If the log names an error you can't place, it belongs in a bug report. It is the single most useful thing to include.

The palette cache is missing or empty. Set a wallpaper through Settings → General, which generates it, or copy a bundled palette into place:

$ cp ~/.config/lucid/themes/nord/quickshell.json ~/.cache/quickshell/matugen.json

That is deliberate. The glass frosts whatever is really behind it, windows included. If you'd rather it frost only the wallpaper, which gives a steadier tint but stops windows showing through, uncomment the rule Lucid ships in ~/.config/hypr/modules/layerrules.lua, or add it to your own Lua config:

hl.layer_rule({ match = { namespace = "quickshell" }, xray = true })

Then reload Hyprland with Super+R or hyprctl reload.

Under Hyprland there is no xsettings daemon, so GTK 3 and GTK 4 read ~/.config/gtk-{3,4}.0/settings.ini while GNOME apps and portals read gsettings. The installer writes both. If only some apps changed, check they agree:

$ gsettings get org.gnome.desktop.interface gtk-theme    # adw-gtk3-dark
$ gsettings get org.gnome.desktop.interface icon-theme   # FairyWren_Dark
$ grep -E 'theme-name' ~/.config/gtk-3.0/settings.ini ~/.config/gtk-4.0/settings.ini

The icons live in ~/.local/share/icons/FairyWren_Dark. If that folder is missing, the installer couldn't reach GitLab; clone FairyWren-Icons by hand.

Paste the URL of any colour-scheme repo into Settings → Theme. Lucid clones it, reads base16, base24 or name-keyed JSON exactly, falls back to sorting the hex codes it finds, and builds a full Material 3 palette. Wallpapers in the repo come along too. Nothing from the repo is ever run: only text is parsed and only images are copied.

Use Light or dark on the Theme page. Every palette has both. Wallpaper palettes are re-extracted in the mode you pick, and the fixed ones get a light version built from their own colours. Accent tint on the General page sets how much of the accent the light surfaces carry. GTK and Qt apps switch with it where a light counterpart of their theme is installed.

Yes. Add a line per output to ~/.config/lucid/wallpaper-outputs.conf. Any argument that is a file becomes that output's picture; the rest is passed to awww.

DP-3      --resize fit --fill-color 000000
HDMI-A-1  ~/Pictures/wallpapers/second.jpg

Colours still come from the wallpaper you picked. qs ipc call displays list prints your outputs.

Google Sans isn't in the Arch repos. Without it Qt falls back to your default sans and everything still works, or you can pick any installed font in Settings → General.

Qt refuses threaded OpenGL on the proprietary NVIDIA driver (its workaround for QTBUG-95817), so Qt Quick falls back to a render loop pinned to about 60 fps however fast your monitor runs. That is why Hyprland stays smooth while the shell does not.

Lucid starts through ~/.config/lucid/launch-shell.sh, which moves those machines to Qt's Vulkan backend, where the smooth loop comes back. Ask it what it decided:

$ ~/.config/lucid/launch-shell.sh --explain

It switches only when NVIDIA is the GPU the compositor renders on, the driver is 555 or newer, and an NVIDIA Vulkan driver is present. Override it with LUCID_RHI_BACKEND=vulkan or LUCID_RHI_BACKEND=opengl; an existing QSG_RHI_BACKEND always wins.

A fractional monitor scale puts icons on fractional pixels. Use a whole-number scale, or adjust the icon size in Settings. The Displays page labels each scale with the room it leaves and warns about ones that don't divide the panel evenly.

Pick the display in Settings → Displays. The bar and the dock can each be sent to a display of their own. Unplug the display the shell is on and it moves to one that's left, then back when you plug it in. From a keybind:

$ qs ipc call -- displays shell next

Instead of next, use an output name, left, middle, right, here, prev or auto.

Only one program can own org.freedesktop.Notifications. Any other notification daemon that is merely installed (swaync, dunst, mako) gets started by the first notification and keeps the name for the whole session. Check who holds it:

$ busctl --user status org.freedesktop.Notifications | grep PID

If that isn't quickshell, mask the other daemon and log back in. The installer offers to do this for you.

$ systemctl --user mask swaync.service   # or dunst.service, mako.service
$ pkill swaync

cava is running without ~/.config/cava/quickshell.conf, so it emits its own terminal output rather than the raw frames the strip reads. Run the installer again, or copy the file from the repo yourself:

$ cp support/cava/quickshell.conf ~/.config/cava/quickshell.conf

Clipboard history needs cliphist. Without it the launcher's Clipboard mode says so and the switch on the Dock settings page is greyed out. The shell runs the watchers that feed it, so history records for as long as the shell is running, and not before it starts.

Get a free Giphy key (email only, no card) from developers.giphy.com and put it in ~/.config/quickshell/lucidmoji/config.json. Tenor works too.

{ "giphyKey": "your-key-here", "tenorKey": "", "gifDir": "" }

Add -- before the target. Without it, qs reads the argument as one of its own and refuses the call with “The following argument was not expected”.

$ qs ipc call -- settings show bar

Calls without arguments work either way, so using -- everywhere is the safe habit.

Everything is exposed over IPC, so bind the calls from your own Lua config (Hyprland 0.55.6 and newer):

hl.bind("SUPER + space", hl.dsp.exec_cmd("qs ipc call -- launcher toggle"))
hl.bind("SUPER + L",     hl.dsp.exec_cmd("qs ipc call -- lock lock"))
hl.bind("SUPER + comma", hl.dsp.exec_cmd("qs ipc call -- settings open"))

Special workspaces are Hyprland Lua: copy support/hypr/modules/specials.lua into ~/.config/hypr/modules/ and bind its functions.

In the Keybinds section of the docs. They live in ~/.config/hypr/modules/binds.lua, and hyprctl reload picks up any change you make there.

Your account password. The lock checks it through PAM against /etc/pam.d/login, the same service a display manager uses, so any account can unlock, not only sudoers. If PAM asks a second question, like a token, the field reopens with PAM's own prompt.

Nothing in the lock IPC target bypasses the password. PAM is the only way in.

That is faillock, and the lock screen is reading its real numbers. With Arch's defaults, three failures within 15 minutes lock the account for 10 minutes, and the screen counts down to when you can try again. You can see the tally yourself:

$ faillock --user "$USER"

An administrator can clear it early with faillock --user <name> --reset as root. The limits themselves live in /etc/security/faillock.conf.

Cancelling an administrator prompt counts too. Every dismissed polkit request is recorded as a failure, so closing three prompts in a row can lock you out just like three wrong passwords. That is polkit and PAM's behaviour, not something Lucid adds.

Lucid registers itself as the session's authentication agent, and only one agent can hold a session. Stop starting any other, like polkit-kde-authentication-agent-1 or polkit-gnome, from your autostart. Lucid drives polkit's own helper, so nothing else is needed.

When SDDM is present the installer copies the theme in, but it never switches to it. To use it, set Current=lucid in the [Theme] section of /etc/sddm.conf:

[Theme]
Current=lucid

Put it in /etc/sddm.conf itself. That file outranks anything in /etc/sddm.conf.d/, so a drop-in there loses if sddm.conf names a theme of its own. The login screen is painted from the running shell's colours, so it follows a theme change.

The Users and Accounts page guards two things: the last administrator can't demote themselves, and an account that is signed in can't be renamed. Everything else, from passwords to groups, goes through AccountsService, so the shell's own polkit dialog asks and nothing runs as root.