// derivatives
MangoWM with Noctalia Shell: Full Setup Guide
dwl-based Wayland compositor with tag layouts, animations, and the Noctalia shell
# MangoWM with Noctalia Shell Installation Guide
1. What is MangoWM?
MangoWM (Mango) is a lightweight, feature-rich Wayland compositor built on dwl — which is itself a Wayland port of dwm. It combines the minimalist philosophy of suckless tiling window managers with modern Wayland features including smooth animations, blur and shadow effects, corner rounding, and zero-flicker rendering via the scenefx library.
Unlike traditional workspace-based compositors, MangoWM uses a tag-based system (inherited from dwm), allowing windows to appear on multiple tags simultaneously and giving each tag its own independent layout.
Core highlights:
– 10+ tiling layouts (tile, scroller, monocle, grid, deck, center_tile, and more)
– Animations for window open/close, tag switching, and focus changes
– Blur, shadow, and corner radius effects via scenefx
– IPC control via the mmsg and mangoctl tools
– XWayland compatibility for legacy X11 applications
– Hot-reload configuration without restarting the compositor
– Overview mode (Hycov-style) and named scratchpads
– Per-tag layout rules
—
2. The Mango Ecosystem
| Component | Role | Package | |———–|——|———| |mango | Wayland compositor | mangowm-git (AUR) |
| mmsg / mangoctl | IPC tools for scripting | included with mangowm |
| waybar | Status bar (fallback/alternative) | waybar |
| noctalia-shell | Full desktop shell (primary) | noctalia-shell (AUR) |
| foot | Default terminal emulator | foot |
| fuzzel | Application launcher | fuzzel |
| swww | Wallpaper daemon with transitions | swww |
| swaync | Notification center | swaync |
| grim + slurp | Screenshots | grim, slurp |
| wl-clipboard | Clipboard utilities | wl-clipboard |
| xdg-desktop-portal-wlr | Screen sharing / portals | xdg-desktop-portal-wlr |
—
3. Prerequisites
Ensure your system is up to date and that you have an AUR helper installed:
sudo pacman -Syu
sudo pacman -S --needed base-devel git
# Install yay if not already installed
git clone https://aur.archlinux.org/yay.git /tmp/yay
cd /tmp/yay && makepkg -si
—
4. Installing MangoWM
MangoWM is available in the AUR as mangowm-git (latest development version):
yay -S mangowm-git
This pulls all required dependencies automatically:
– wayland, wayland-protocols
– libinput, libdrm, libdisplay-info, libliftoff
– libxkbcommon, pixman, hwdata, seatd, pcre2
– xorg-xwayland, libxcb
– wlroots (0.19.3) and scenefx (0.4.1) are built from source as part of the AUR package
Install Recommended Applications
Install the full set of companion applications:
# Terminal, launcher, wallpaper, notifications, screenshots
sudo pacman -S --needed \
foot \
fuzzel \
swww \
swaync \
grim \
slurp \
wl-clipboard \
cliphist \
brightnessctl \
wlsunset \
imv \
mpv \
thunar \
firefox \
polkit-gnome \
gnome-keyring \
xdg-desktop-portal \
xdg-desktop-portal-gtk \
ttf-jetbrains-mono-nerd \
noto-fonts \
noto-fonts-emoji
# AUR packages
yay -S \
xdg-desktop-portal-wlr \
satty \
wl-clip-persist
Install Default Application Handler
sudo pacman -S --needed xdg-utils handlr-regex
# or
yay -S xdg-utils-handlr
—
5. NVIDIA Setup
MangoWM is wlroots-based, so NVIDIA requires the same kernel module and environment variable configuration as other wlroots compositors.
Install NVIDIA Drivers
sudo pacman -S --needed nvidia nvidia-utils nvidia-settings
Enable DRM Kernel Mode Setting
Create a modprobe configuration file:
sudo nano /etc/modprobe.d/nvidia.conf
options nvidia-drm modeset=1 fbdev=1
Regenerate the initramfs and update GRUB:
sudo mkinitcpio -P
sudo grub-mkconfig -o /boot/grub/grub.cfg
Reboot after this step.
VRAM Size Fix (if needed)
Some NVIDIA cards report incorrect VRAM sizes. Create a DRM fix file:
sudo nano /etc/udev/rules.d/61-nvidia-drm-vram.rules
ACTION=="add|bind", KERNEL=="card*", SUBSYSTEM=="drm", DRIVERS=="nvidia", ATTR{device/resource_sizes}=="*"
NVIDIA Environment Variables
These will be set in your MangoWM autostart script (see Section 10). The key variables for NVIDIA on wlroots compositors:
LIBVA_DRIVER_NAME=nvidia
GBM_BACKEND=nvidia-drm
__GLX_VENDOR_LIBRARY_NAME=nvidia
WLR_NO_HARDWARE_CURSORS=1
Note: __GLX_VENDOR_LIBRARY_NAME=nvidia may cause login issues on some setups. If MangoWM fails to start, try removing that variable first.
Verify NVIDIA After Boot
From a TTY (before starting MangoWM), verify VAAPI hardware acceleration:
# Find your render node (Intel is usually renderD128 or renderD129)
ls -la /dev/dri/by-path/
# Test Intel VA-API (for hardware decode)
LIBVA_DRIVER_NAME=iHD vainfo --display drm --device /dev/dri/renderD129
# Test NVIDIA VA-API
LIBVA_DRIVER_NAME=nvidia vainfo --display drm --device /dev/dri/renderD128
—
6. Configuration File
Copy the default config to your user directory:
mkdir -p ~/.config/mango
cp /usr/share/mango/config.conf ~/.config/mango/config.conf
Full config.conf
Below is a complete, annotated configuration file:
# ~/.config/mango/config.conf
# MangoWM configuration — reload with Super+R or: mangoctl reload
# ── Appearance ───────────────────────────────────────────────────────────────
# Border thickness in pixels
borderpx=2
# Corner radius in pixels (requires scenefx)
border_radius=8
# Hide borders when only one window is open
no_border_when_single=1
# Border colors (0xRRGGBBAA)
bordercolor=0x333333ff
focuscolor=0x89b4faff
urgentcolor=0xf38ba8ff
maximizescreencolor=0xa6e3a1ff
scratchpadcolor=0x89dcebff
globalcolor=0xcba6f7ff
overlaycolor=0x94e2d5ff
rootcolor=0x1e1e2eff
# ── Gaps ─────────────────────────────────────────────────────────────────────
# Inner gaps (between windows): horizontal and vertical
gappih=6
gappiv=6
# Outer gaps (screen edge): horizontal and vertical
gappoh=8
gappov=8
# Automatically remove gaps when only one window is visible
smartgaps=1
# ── Opacity ──────────────────────────────────────────────────────────────────
focused_opacity=1.0
unfocused_opacity=0.90
# ── Blur ─────────────────────────────────────────────────────────────────────
# Enable blur for windows
blur=1
# Enable blur for layer surfaces (bars, launchers, shell)
blur_layer=1
# Optimized blur algorithm (recommended)
blur_optimized=1
# Number of blur passes (higher = softer, more GPU)
blur_params_num_passes=3
# Blur radius in pixels
blur_params_radius=6
# Noise, brightness, contrast, saturation adjustments
blur_params_noise=0.02
blur_params_brightness=0.90
blur_params_contrast=0.90
blur_params_saturation=1.2
# ── Shadows ──────────────────────────────────────────────────────────────────
# Enable shadows for windows
shadows=1
# Enable shadows for layer surfaces
layer_shadows=0
# Restrict shadows to floating windows only (0 = all windows)
shadow_only_floating=0
# Shadow size and softness
shadows_size=12
shadows_blur=20
# Shadow color (semi-transparent black)
shadowscolor=0x000000bb
# Shadow offset
shadows_position_x=0
shadows_position_y=4
# ── Animations ───────────────────────────────────────────────────────────────
# Enable window animations
animations=1
# Enable layer surface animations (bars, launchers)
layer_animations=1
# Animation type: slide or zoom
animation_type_open=slide
animation_type_close=slide
# Fade effects
animation_fade_in=1
animation_fade_out=1
fadein_begin_opacity=0.5
fadeout_begin_opacity=0.8
# Zoom parameters (when animation_type = zoom)
zoom_initial_ratio=0.3
zoom_end_ratio=0.8
# Tag switch direction: 1 = horizontal, 0 = vertical
tag_animation_direction=1
# Animation durations in milliseconds
animation_duration_open=350
animation_duration_close=700
animation_duration_move=400
animation_duration_tag=300
animation_duration_focus=0
# Bezier curves (cubic: x1,y1,x2,y2)
animation_curve_open=0.46,1.0,0.29,1
animation_curve_close=0.08,0.92,0,1
animation_curve_move=0.46,1.0,0.29,1
animation_curve_tag=0.46,1.0,0.29,1
# ── Input ────────────────────────────────────────────────────────────────────
# Keyboard layout
keyboard_layout=us
# Key repeat: rate (keys/sec) and initial delay (ms)
repeat_rate=25
repeat_delay=600
# Touchpad
tap_to_click=1
natural_scroll=1
# ── Master Layout ─────────────────────────────────────────────────────────────
# Master area size ratio (0.0–1.0)
default_mfact=0.55
# ── Overview & Scratchpad ─────────────────────────────────────────────────────
overviewgappi=5
overviewgappo=30
enable_hotarea=1
hotarea_size=10
scratchpad_width_ratio=0.80
scratchpad_height_ratio=0.85
# ── Autostart ─────────────────────────────────────────────────────────────────
# Executed once when MangoWM starts
# Wallpaper daemon
exec=swww-daemon
# Noctalia shell (see Section 7)
exec=noctalia
# Authentication agent
exec=/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1
# Keyring
exec=gnome-keyring-daemon --start --components=secrets
# Clipboard persistence
exec=wl-clip-persist --clipboard both
# Night light (adjust temperature and location as needed)
exec=wlsunset -l 40.7 -L -74.0
# Set a wallpaper (fallback if swww hasn't started)
# exec=swaybg -i ~/Pictures/wallpapers/wall.png -m fill
# ── Keybindings ───────────────────────────────────────────────────────────────
# Terminal
bind=ALT,Return,spawn,foot
# Application launcher
bind=SUPER,d,spawn,fuzzel
# Kill focused window
bind=ALT,q,killclient
# Reload configuration
bind=SUPER,r,reload_config
# Quit MangoWM
bind=SUPER,m,quit
# Toggle floating
bind=ALT,backslash,toggle_float
# Toggle fullscreen
bind=ALT,f,toggle_fullscreen
# Toggle overlay (float above all)
bind=SUPER,o,toggle_overlay
# Cycle through layouts
bind=SUPER,n,cycle_layout
# Focus next / previous window
bind=SUPER,Tab,focusnext
bind=SUPER+SHIFT,Tab,focusprev
# Resize master area
bind=SUPER,equal,incmaster
bind=SUPER,minus,decmaster
# Overview mode (Hycov-style all-window view)
bind=SUPER,grave,toggle_overview
# Screenshots
bind=SUPER,s,spawn,grim -g "$(slurp)" - | satty --filename -
bind=SUPER+SHIFT,s,spawn,grim ~/Pictures/Screenshots/$(date +%Y%m%d_%H%M%S).png
# Notifications (swaync toggle panel)
bind=SUPER,n,spawn,swaync-client -t
# Lock screen
bind=SUPER+SHIFT,l,spawn,swaylock
# File manager
bind=SUPER,e,spawn,thunar
# ── Tag Navigation ────────────────────────────────────────────────────────────
# View tags 1–9
bind=CTRL,1,view_tag,1
bind=CTRL,2,view_tag,2
bind=CTRL,3,view_tag,3
bind=CTRL,4,view_tag,4
bind=CTRL,5,view_tag,5
bind=CTRL,6,view_tag,6
bind=CTRL,7,view_tag,7
bind=CTRL,8,view_tag,8
bind=CTRL,9,view_tag,9
# Move focused window to tag 1–9
bind=ALT,1,set_tag,1
bind=ALT,2,set_tag,2
bind=ALT,3,set_tag,3
bind=ALT,4,set_tag,4
bind=ALT,5,set_tag,5
bind=ALT,6,set_tag,6
bind=ALT,7,set_tag,7
bind=ALT,8,set_tag,8
bind=ALT,9,set_tag,9
# Navigate left/right between tags
bind=SUPER,Left,view_tag_prev
bind=SUPER,Right,view_tag_next
# ── Multi-Monitor ─────────────────────────────────────────────────────────────
# Focus next/previous monitor
bind=ALT+SHIFT,Left,focusmon_prev
bind=ALT+SHIFT,Right,focusmon_next
# Move window to next/previous monitor
bind=SUPER+ALT,Left,tagmon_prev
bind=SUPER+ALT,Right,tagmon_next
# ── Gaps ─────────────────────────────────────────────────────────────────────
bind=ALT+SHIFT,x,incgaps,5
bind=ALT+SHIFT,z,decgaps,5
# ── Mouse Bindings ────────────────────────────────────────────────────────────
# Move window (hold Super, drag with left button)
mousebind=SUPER,left,move_window
# Resize window (hold Super, drag with right button)
mousebind=SUPER,right,resize_window
# Maximize with middle click
mousebind=NONE,middle,toggle_maximize
# ── Scroll Bindings ───────────────────────────────────────────────────────────
# Scroll through tags with Super+scroll
axisbind=SUPER,scroll_up,view_tag_prev
axisbind=SUPER,scroll_down,view_tag_next
# ── Tag Rules ─────────────────────────────────────────────────────────────────
# Set default layouts per tag
tagrule=id:1,layout_name:tile
tagrule=id:2,layout_name:scroller
tagrule=id:3,layout_name:tile
tagrule=id:4,layout_name:grid
tagrule=id:5,layout_name:monocle
tagrule=id:6,layout_name:tile
tagrule=id:7,layout_name:deck
tagrule=id:8,layout_name:tile
tagrule=id:9,layout_name:tile
# ── Layer Rules ───────────────────────────────────────────────────────────────
# Noctalia shell animations
layerrule=animation_type_open:zoom,layer_name:noctalia
layerrule=animation_type_close:zoom,layer_name:noctalia
# Launcher animations
layerrule=animation_type_open:zoom,layer_name:fuzzel
layerrule=animation_type_close:zoom,layer_name:fuzzel
# Notification animations
layerrule=animation_type_open:slide,layer_name:swaync
layerrule=animation_type_close:slide,layer_name:swaync
Reload changes: PressSuper+Ror runmangoctl reloadfrom a terminal. Input device changes (keyboard layout, touchpad) require logging out and back in.
—
7. Noctalia Shell
Noctalia is a full desktop shell built on Quickshell (a Wayland QML shell framework). It provides a panel, app launcher, notification integration, system tray, and workspace/tag indicators — all as Wayland layer surfaces compatible with any Wayland compositor including MangoWM.
Installation
Noctalia requires noctalia-qs instead of the upstream quickshell package — they conflict:
# Remove upstream quickshell if installed
sudo pacman -Rns quickshell 2>/dev/null || true
# Install Noctalia (pulls noctalia-qs as dependency)
yay -S noctalia-shell
If pacman warns about a conflict betweenquickshellandnoctalia-qs, confirm the replacement.noctalia-qsis a patched build of Quickshell that Noctalia requires.
Verify Installation
which noctalia
noctalia --version
MangoWM Integration
Noctalia launches as Wayland layer surfaces and integrates with MangoWM via the standard Wayland layer-shell protocol. No special MangoWM modules are required.
The exec=noctalia line in config.conf (Section 6) handles autostart. To test Noctalia without restarting MangoWM:
noctalia &
To restart Noctalia:
pkill noctalia; sleep 0.5; noctalia &
Noctalia Configuration
Noctalia configuration lives at ~/.config/noctalia/:
# Copy the default config if it doesn't exist
mkdir -p ~/.config/noctalia
# Default config is generated on first run
noctalia
Adjust colors and layout in ~/.config/noctalia/config.json to match your MangoWM theme. Refer to the Noctalia documentation for the full configuration reference.
Disabling Waybar When Using Noctalia
If you have Waybar in your autostart from a previous setup, comment it out so they do not conflict:
# In ~/.config/mango/config.conf
# exec=waybar # disabled — using Noctalia instead
exec=noctalia
—
8. Waybar (Alternative Status Bar)
If you prefer Waybar over Noctalia, install and configure it as follows.
Installation
sudo pacman -S waybar
MangoWM Waybar Config
MangoWM supports a dedicated Waybar module. Create the config:
mkdir -p ~/.config/mango
Create ~/.config/mango/config.jsonc:
{
"layer": "top",
"position": "top",
"height": 32,
"spacing": 4,
"modules-left": ["custom/mango-tags", "custom/mango-layout", "custom/mango-title"],
"modules-center": ["clock"],
"modules-right": ["pulseaudio", "network", "cpu", "memory", "battery", "tray"],
"clock": {
"format": " {:%H:%M}",
"format-alt": " {:%A, %B %d, %Y}"
},
"cpu": {
"format": " {usage}%",
"interval": 2
},
"memory": {
"format": " {used:.1f}G"
},
"battery": {
"format": "{icon} {capacity}%",
"format-icons": ["", "", "", "", ""],
"states": { "warning": 30, "critical": 15 }
},
"network": {
"format-wifi": " {essid}",
"format-ethernet": " {ipaddr}",
"format-disconnected": " Disconnected"
},
"pulseaudio": {
"format": "{icon} {volume}%",
"format-muted": "",
"format-icons": { "default": ["", "", ""] }
},
"tray": {
"spacing": 8
}
}
Launch Waybar via autostart in config.conf:
exec=waybar -c ~/.config/mango/config.jsonc -s ~/.config/mango/style.css
—
9. Default Applications
Install xdg-utils and a Default App Manager
sudo pacman -S --needed xdg-utils
yay -S handlr-regex
Set Default Applications
# Web browser
handlr set x-scheme-handler/http firefox.desktop
handlr set x-scheme-handler/https firefox.desktop
handlr set text/html firefox.desktop
# Terminal emulator
handlr set x-scheme-handler/terminal foot.desktop
# File manager
handlr set inode/directory thunar.desktop
# Image viewer
handlr set image/png imv.desktop
handlr set image/jpeg imv.desktop
handlr set image/gif imv.desktop
handlr set image/webp imv.desktop
# Video player
handlr set video/mp4 mpv.desktop
handlr set video/mkv mpv.desktop
handlr set video/webm mpv.desktop
# PDF viewer
handlr set application/pdf zathura.desktop
# Text editor
handlr set text/plain nvim.desktop
Verify
handlr list
xdg-mime query default x-scheme-handler/http
—
10. Services
Enable the following systemd services:
# Pipewire audio (if not already active)
systemctl --user enable --now pipewire pipewire-pulse wireplumber
# Polkit authentication agent (autostarted via exec= in config.conf)
# No service needed — launched directly
# GNOME Keyring (for credentials)
systemctl --user enable --now gnome-keyring-daemon
XDG Desktop Portals
Portals are needed for screen sharing, file picker dialogs, and Flatpak:
sudo pacman -S --needed \
xdg-desktop-portal \
xdg-desktop-portal-gtk
yay -S xdg-desktop-portal-wlr
Enable the portal service:
systemctl --user enable --now xdg-desktop-portal
systemctl --user enable --now xdg-desktop-portal-wlr
—
11. Starting MangoWM
From a TTY
Set the NVIDIA environment variables and launch:
export LIBVA_DRIVER_NAME=nvidia
export GBM_BACKEND=nvidia-drm
export __GLX_VENDOR_LIBRARY_NAME=nvidia
export WLR_NO_HARDWARE_CURSORS=1
mango
To avoid typing these every time, create a launch script:
nano ~/.local/bin/start-mango
#!/bin/bash
export LIBVA_DRIVER_NAME=nvidia
export GBM_BACKEND=nvidia-drm
export __GLX_VENDOR_LIBRARY_NAME=nvidia
export WLR_NO_HARDWARE_CURSORS=1
exec mango
chmod +x ~/.local/bin/start-mango
Then launch with:
start-mango
From a Display Manager
MangoWM installs a .desktop entry for display managers (SDDM, GDM, LightDM). Select Mango from the session menu at login.
For NVIDIA with a display manager, set the environment variables in /etc/environment:
sudo nano /etc/environment
LIBVA_DRIVER_NAME=nvidia
GBM_BACKEND=nvidia-drm
__GLX_VENDOR_LIBRARY_NAME=nvidia
WLR_NO_HARDWARE_CURSORS=1
Reboot after editing /etc/environment.
Reload and Exit
| Action | Keybind | CLI | |——–|———|—–| | Reload config |Super+R | mangoctl reload |
| Exit MangoWM | Super+M | mangoctl quit |
—
12. Default Keybindings Reference
| Action | Keybind | |——–|———| | Open terminal |Alt + Enter |
| Open launcher | Super + D |
| Kill window | Alt + Q |
| Toggle floating | Alt + \ |
| Toggle fullscreen | Alt + F |
| Toggle overlay | Super + O |
| Overview mode | Super + \` |
| Cycle layout | Super + N |
| Focus next window | Super + Tab |
| Focus previous window | Super + Shift + Tab |
| View tag 1–9 | Ctrl + 1–9 |
| Move window to tag 1–9 | Alt + 1–9 |
| Navigate tags | Super + Left / Right |
| Focus monitor | Alt + Shift + Left / Right |
| Move window to monitor | Super + Alt + Left / Right |
| Increase / decrease gaps | Alt + Shift + X / Z |
| Screenshot (region) | Super + S |
| Screenshot (full) | Super + Shift + S |
| File manager | Super + E |
| Notifications | Super + N |
| Reload config | Super + R |
| Quit MangoWM | Super + M |
| Move window | Super + Left Click |
| Resize window | Super + Right Click |
| Maximize window | Middle Click |
| Scroll through tags | Super + Scroll |
—
13. Layouts
MangoWM supports over 10 tiling layouts selectable per tag or cycled with Super+N:
tile | Classic master-stack: one master on left, stack on right |
| scroller | Windows scroll horizontally like a scrollable list |
| monocle | One window at a time, fullscreen without gaps |
| grid | Equal-size grid of all windows |
| deck | Stacked cards: master + one visible stack window |
| center_tile | Master centered with stacks on both sides |
| vertical_tile | Master on top, stack below |
| vertical_scroller | Windows scroll vertically |
| vertical_grid | Vertical equal-size grid |
| tgmix | Mixed tag/grid hybrid |
Set per-tag defaults in config.conf with tagrule=id:N,layout_name:layout.
—
14. NVIDIA Troubleshooting
MangoWM Fails to Start
If you see a blank screen or immediate crash after running mango:
1. Remove __GLX_VENDOR_LIBRARY_NAME=nvidia from your environment — this variable causes login failures on some setups. Try launching without it first.
2. Confirm nvidia-drm.modeset=1 is set: cat /sys/module/nvidia_drm/parameters/modeset should output Y.
3. Check for errors: mango 2>&1 | head -50
Screen Tearing or Artifacts
# Add to /etc/environment if not already set
WLR_DRM_NO_ATOMIC=1
Cursor Invisible or Flickering
Ensure WLR_NO_HARDWARE_CURSORS=1 is set in your environment before launching MangoWM.
Hardware Video Acceleration
On dual-GPU laptops (Intel iGPU + NVIDIA dGPU), the Intel GPU is used for VA-API decode by default:
# Find the Intel render node (look for pci-0000:00:02.0)
ls -la /dev/dri/by-path/
# Test — try renderD128 first, then renderD129 if that fails
LIBVA_DRIVER_NAME=iHD vainfo --display drm --device /dev/dri/renderD128
LIBVA_DRIVER_NAME=iHD vainfo --display drm --device /dev/dri/renderD129
Applications Not Inheriting Environment Variables
Environment variables set in /etc/environment or ~/.bash_profile are inherited by MangoWM and all child processes. Variables set only in your shell’s ~/.bashrc are not available to MangoWM unless you launch it directly from that shell.
Use /etc/environment for system-wide Wayland/NVIDIA variables, or set them in your start-mango launch script.
// categories
// recent posts