A macOS Tahoe–style menu bar + Dock for Hyprland, built on Quickshell,
with a real-time Liquid Glass refraction shader, and a lock screen, MacLock.

_{Quick showcase (OLD)}

Screenshots · Requirements · Install · Updating · Hyprland config · MacLock · Troubleshooting

A macOS Tahoe–style menu bar + Dock for Hyprland, built on Quickshell, with a real-time "Liquid Glass" refraction shader, window previews, Spotlight, clipboard/emoji picker, notifications, Control Center, screenshots, screen recording, desktop widgets (weather, calendar, clock, music player), a wallpaper picker, an Alt+Tab switcher and a full lock screen, all in one Quickshell process.

The repository also ships MacLock, a matching Liquid Glass lock screen. It is a separate Quickshell config on purpose: it runs as its own process, so a shell crash can never take the lock with it.

Best icon pack for the shell: https://github.com/Scrimas/MacOS-Like

Heads up: this targets Hyprland 0.55+ with a Lua config (hyprland.lua) and a recent Quickshell (0.3.x). See Requirements and Known issues.

The whole desktop: widgets, the menu bar on top and the Dock at the bottom.

The Dock, with Liquid Glass.

Control Center (New)

Lock screen

Lock screen media player

MacShell/               (this repository)
├── install.sh          installer / updater
├── README.md
├── MacShell/           the shell      ->  ~/.config/quickshell/MacShell
└── MacLock/            the lock screen ->  ~/.config/quickshell/MacLock

The two are installed as separate Quickshell configs (neither lives inside the other).

MacShell

MacLock

and more files...

This shell replaces your bar, dock and notification daemon. Stop anything that overlaps:

• Other bars/shells (waybar, hyprpanel, ags, Noctalia, Caelestia, …) and docks (nwg-dock, …).
• Notification daemons (dunst, mako, swaync): the bar owns org.freedesktop.Notifications. systemctl --user disable --now dunst (or mako / swaync).

1. Install the requirements above. On Arch, for example:

    sudo pacman -Syu
    
    sudo pacman -S --needed \
      hyprland quickshell hyprlock awww \
      qt6-base qt6-declarative qt6-wayland qt6-shadertools qt6-svg \
      grim slurp wl-clipboard wf-recorder cliphist \
      libnotify brightnessctl \
      networkmanager bluez bluez-utils \
      inotify-tools \
      inter-font noto-fonts noto-fonts-emoji \
      xdg-desktop-portal-hyprland \
      xdg-utils polkit \
      pipewire wireplumber pipewire-pulse \
      kitty

   Other distros: install the equivalents. Fedora has a Quickshell COPR; Nix has pkgs.quickshell. You can skip this: the installer checks every requirement (tools, Qt libraries, fonts, icon theme, portals, hyprlock, the optional helpers such as awww, zenity, slurp, ffmpeg) and installs the missing ones for you with pacman, dnf or apt, after asking once (-y skips the question). Packages that are not in the main repositories, such as quickshell or awww, come from the AUR (yay / paru; on Arch the installer can build yay for you) or the Fedora COPR. It also enables the bluetooth service, which Bluetooth needs. bash install.sh --deps-only does just this step. Hyprland 0.55+ with a Lua config may need a newer package than your distro ships, so check hyprctl version. Debian/Ubuntu have no quickshell / hyprland packages: build those from source.

2. Run the installer, either from a clone:

   git clone https://github.com/0-ss/MacShell
   cd MacShell
   bash install.sh

   or in one line:

   curl -fsSL https://raw.githubusercontent.com/0-ss/MacShell/main/install.sh | bash

   The installer will create a new .lua file in your /.config/hypr/ that have keybinds and auto start, so you don't need to to manually bind MacShell.

   It installs MacShell to ~/.config/quickshell/MacShell and MacLock to ~/.config/quickshell/MacLock, and adds the autostart and keybinds to your Hyprland config: a .lua file called macshell.lua which is located here /.config/hypr/ (Hyprland 0.55+), when there is no Lua config. The block runs ~/.local/bin/macshell-start, which waits for the compositor, never starts a second copy and restarts the shell if it crashes. Remove the block between the MacShell (added by install.sh) markers to undo it. Your settings are never touched, and the previous install is backed up first (last 3 kept in ~/.local/share/macshell/backups/).

   When run from a clone, the installer first checks GitHub: if the repository has a newer version (and your clone has no uncommitted changes) it downloads and installs that one automatically.

   Don't reach the install folders through a symlink; Quickshell ≥ 0.3 derives its state folders from the link path.

3. Try it:

   qs -c MacShell

   On first run with the Liquid Glass style, liquidglass.frag is compiled with qsb and cached in ~/.config/macdock/liquidglass.frag.qsb. Watch for [macbar-glass] state: ready in the log.

4. Add the Hyprland config below, then autostart it.

Environment: MACSHELL_REPO, MACSHELL_BRANCH, MACSHELL_CHANNEL, MACSHELL_DEST, MACLOCK_DEST, GITHUB_TOKEN.

The Best way to make sure you have the latest update Is to delete the MacShell folder in /home (IF needed) and run this again :

git clone https://github.com/0-ss/MacShell
cd MacShell
bash install.sh

Then Choose install

MacShell (installed: a1b2c3d4e5f6)

  1) Install shell (Best for install and updating)
  2) Check for updates (Only checks for updates)
  3) Uninstall shell
  4) Bind help
  q) Quit

• Install shell installs MacShell and MacLock (or reinstalls them).
• Check for updates compares your version with GitHub and, if there is a newer one, asks whether to install it (y/n).
• Uninstall shell removes MacShell and MacLock (your settings are kept).
• Bind help opens the Hyprland keybind section of this README in your browser.

The other tools are still available as options: --doctor, --low-power, --deps-only (see --help).

An update also installs the dependencies the new version needs, updates MacShell and MacLock together, saves the old install first, and never touches your settings. The command-line tool is still there for scripts and the daily timer:

macshell-update check       # is there a newer version?
macshell-update log         # what changed since the installed version
macshell-update update      # download and install it (MacShell and MacLock), including new dependencies
macshell-update rollback    # go back to the previous install (MacShell and MacLock)
macshell-update channel main   # follow the newest commit instead of releases (or: release)
macshell-update status

macshell-update update runs the new version's installer too, so new files, new dependencies and a new start script come along. It keeps the last 3 installs, and does one update at a time. Dependencies are installed only when sudo works without a password (an unattended timer cannot type one); otherwise you get a notice listing what to install with bash install.sh --deps-only.

The shell also checks by itself and tells you. bash install.sh --check does the same check from a clone, and bash install.sh --auto-update installs a daily timer (systemctl --user list-timers macshell-update.timer) so updates install without you doing anything. MacShell reloads itself after an update; MacLock picks up the new files the next time it locks.

-- autostart (remove other bars / docks / notification daemons first).
-- install.sh adds this for you; macshell-start waits for the compositor and restarts the shell if it crashes.
hl.on("hyprland.start", function()
    hl.exec_cmd("sh ~/.local/bin/macshell-start")
end)

-- layer rules: blur for the glass surfaces
hl.layer_rule({ name = "macdock",  match = { namespace = "macdock"  }, blur = true, ignore_alpha = 0.2,  no_anim = true })
hl.layer_rule({ name = "macspot",  match = { namespace = "macspot"  }, blur = true, ignore_alpha = 0.05, no_anim = true })
hl.layer_rule({ name = "macbarbg", match = { namespace = "macbarbg" }, blur = true, ignore_alpha = 0.05, no_anim = true })
hl.layer_rule({ name = "macshot",  match = { namespace = "macshot"  }, no_anim = true })   -- optional: no fade on the screenshot picker

-- The Settings window floats and centres itself when it opens, so it needs no window rule.

-- keybinds (the name after -c is the config folder name, case-sensitive)
local qs = "qs -c MacShell ipc call "

hl.bind("SUPER + V",          hl.dsp.exec_cmd(qs .. "spotlight clipboard"))
hl.bind("SUPER + period",     hl.dsp.exec_cmd(qs .. "spotlight emoji"))
hl.bind("SUPER + Space",      hl.dsp.exec_cmd(qs .. "spotlight toggle"))
hl.bind("ALT + TAB",          hl.dsp.exec_cmd(qs .. "switcher next"))
hl.bind("CTRL + ALT + W",     hl.dsp.exec_cmd(qs .. "wallpapers toggle"))
hl.bind("PRINT",              hl.dsp.exec_cmd(qs .. "screenshot region"))

-- MacLock (lock screen)
hl.bind("SUPER + L",          hl.dsp.exec_cmd("sh ~/.config/quickshell/MacLock/lock-via-ipc.sh"))

Change SUPER + L if that key is already used. On a classic hyprland.conf the same bind is bind = SUPER, L, exec, sh ~/.config/quickshell/MacLock/lock-via-ipc.sh.

Also make sure blur is enabled in your Hyprland decoration settings, or the "Normal Blur" style won't blur.

qs -c MacShell ipc call <target> <function>

A macOS-style lock screen using the same Liquid Glass look (see the screenshots above). Each lock runs in its own process (a Wayland session lock is used once), and lock-via-ipc.sh starts a fresh one for every lock, so the keybind above is all you need.

sh ~/.config/quickshell/MacLock/lock-via-ipc.sh        # lock now (what the keybind runs)
qs -c MacLock ipc call lockscreen lock                 # same, if an IPC-ready MacLock is already running
qs -c MacLock                                          # lock immediately, one-shot (e.g. from hypridle)
MACLOCK_PREVIEW=1 qs -c MacLock                        # preview the design as a window, no real lock

Passwords are checked with PAM (/etc/pam.d/hyprlock). To lock on idle or before sleep with hypridle, set lock_cmd = sh ~/.config/quickshell/MacLock/lock-via-ipc.sh.

Settings → Desktop & Dock → Icon Tint re-colours every Dock icon with one colour (pick a swatch or type a hex colour) and works with any icon pack: each icon is desaturated and colourised with your colour, with a small brightness lift so light colours (green, yellow...) stay vivid and black stays dark. Strength keeps some of the original colours. It needs no shader build and no extra packages.

Settings → General → Desktop Widgets. Weather, Calendar, Clock, Player and Image widgets, each in Small, Medium and Large. Widget size scales every widget and the grid together (60 % to 150 %); widgets snap back onto the grid when you let go of the slider.

An Image widget shows a picture you choose: press + S / M / L on the Image row and pick a file (needs zenity, kdialog or yad). The picture is copied to ~/.config/macwidgets/images, so it keeps working if the original moves. To change it later use Edit on Desktop and press Choose Image… on the widget.

Changing the wallpaper from Settings, the wallpaper picker (Ctrl+Alt+W) or ipc call wallpapers sets the real desktop wallpaper with awww (its daemon is started automatically if needed), and the widgets, menus and Liquid Glass follow. Light/Dark wallpaper pairs (name-Light.png / name-Dark.png) are applied the same way. Only if awww is missing or fails are the other tools tried: swww, Noctalia, hyprpaper, swaybg. To use your own command, set "wallpaperCmd": "your-command {}" ({} is the image path) in ~/.config/macbar/settings.json. Animated (video) wallpapers need mpvpaper and ffmpeg.

The Liquid Glass refracts your wallpaper, so the shell also needs its file path. It looks, in order, at: the wallpaperPath override in settings.json, Noctalia's settings.toml, awww/swww query, hyprctl hyprpaper listactive, and ~/.config/hypr/hyprpaper.conf. If yours isn't detected (swaybg, wpaperd, a custom script), either pick a wallpaper in the built-in picker (it remembers the path), or set "wallpaperPath": "/path/to/image.png" in ~/.config/macdock/settings.json. The picker reads ~/Pictures/Wallpapers by default (wallpaperDir).

Clipboard history is kept on disk (cliphist's database plus ~/.cache/macbar/clip). Turn it off with clipHistory: false in ~/.config/macbar/settings.json if you don't want that.

1. sudo pacman -Syu, then reboot if the kernel was updated.
2. Install Hyprland 0.55 or newer and make sure you have a hyprland.lua (hyprctl version shows the version).
3. git clone https://github.com/0-ss/MacShell && cd MacShell && bash install.sh and answer yes. It installs every dependency (on Arch it can build yay for awww / mpvpaper), starts the Bluetooth, Wi-Fi, power-profile and audio services, adds the autostart to hyprland.lua, and creates ~/.config/macshell/env.
4. Log out and back in (or run sh ~/.local/bin/macshell-start), then run bash install.sh --doctor if anything looks wrong. On older hardware add --low-power.

Environment variables (QS_ICON_THEME, QT_QPA_PLATFORM, XDG_CURRENT_DESKTOP, ...): macshell-start sets sensible ones before it starts the shell, so it works whether it was started by Hyprland, a terminal or a keybind. Your own go in ~/.config/macshell/env (the installer creates it with commented examples, including QSG_RHI_BACKEND=opengl, QSG_RENDER_LOOP=basic and QT_QUICK_BACKEND=software for old graphics).

Wallpaper after a reboot: awww forgets its image at every shutdown. MacShell remembers the wallpaper you picked in the picker and puts it back at login (and macshell-start runs awww restore first). Pick a wallpaper once after updating and it stays.

Shell crash with wl_display#1: error 0: invalid object NNN when many windows open/close quickly (a game launching, spamming terminals) while live window capture runs. A window closes while a capture frame for it is still pending; Hyprland does not answer that frame, the shell then destroys it, and the compositor drops the Wayland connection. Mitigations:

• Settings → Menu Bar → turn Real-time glass off (far fewer captures; the biggest win).
• Settings → Dock Behavior → turn Live window capture off.
• The shell already pauses glass captures while windows open/close.
• Auto-restart: the autostart the installer adds (macshell-start) already restarts the shell after a crash.

Glitchy window capture (previews or glass showing a wrong or stale frame): turn off Settings → Dock Behavior → Live window capture.

Reproduced on Hyprland 0.56.2 / Quickshell 0.3.2.

Created by Rickky (owner), with vSuol (collaborator). Emoji data from GitHub gemoji (MIT).