Quick Start

Get Mango Wayland Compositor running in minutes

Prerequisites

Before installing Mango, ensure your system has the required dependencies.

Required Dependencies

Arch Linux

sudo pacman -S wayland wayland-protocols libinput libdrm libxkbcommon \
  pixman libdisplay-info libliftoff hwdata seatd pcre2 \
  xorg-xwayland libxcb

Installation

Choose the installation method that works best for your distribution.

Arch Linux

Using AUR Helper

The easiest way to install on Arch Linux is through the AUR:

yay -S mangowm-git

Or with paru:

paru -S mangowm-git

The package is also available for manual download from AUR

Gentoo

Using GURU Repository

1. Add GURU repository

   emerge --ask --verbose eselect-repository
   eselect repository enable guru
   emerge --sync guru
   
2. Accept keywords

   Add gui-libs/scenefx and gui-wm/mangowm to /etc/portage/package.accept_keywords:

   echo "gui-libs/scenefx ~amd64" >> /etc/portage/package.accept_keywords
   echo "gui-wm/mangowm ~amd64" >> /etc/portage/package.accept_keywords
   
3. Install Mango

   emerge --ask --verbose gui-wm/mangowm
   

Fedora

Using Terra Repository

1. Add Terra Repository

   Follow instructions at terra.fyralabs.com

2. Install Mango

   sudo dnf install mangowm
   

Guix System

Using Guix Channel

1. Add Mango channel

   Edit ~/.config/guix/channels.scm:

   ;; In $HOME/.config/guix/channels.scm
   (cons (channel
           (name 'mangowm)
           (url "https://github.com/mangowm/mango.git")
           (branch "main"))
         ... ;; Your other channels
         %default-channels)
   
2. Update and install

   guix pull
   guix install mangowm
   

Build from Source

Manual Build

Building from source requires compiling wlroots and scenefx dependencies first.

1. Install wlroots 0.19.2

   git clone -b 0.19.2 https://gitlab.freedesktop.org/wlroots/wlroots.git
   cd wlroots
   meson build -Dprefix=/usr
   sudo ninja -C build install
   
2. Install scenefx 0.4.1

   git clone -b 0.4.1 https://github.com/wlrfx/scenefx.git
   cd scenefx
   meson build -Dprefix=/usr
   sudo ninja -C build install
   
3. Build and install Mango

   git clone https://github.com/mangowm/mango.git
   cd mango
   meson build -Dprefix=/usr
   sudo ninja -C build install
   

   Mango builds in just a few seconds!

Initial Configuration

Mango uses an external configuration file for easy customization without recompilation.

1. Create config directory

   mkdir -p ~/.config/mango
   
2. Copy default configuration

   The default config is installed to /etc/mango/config.conf. Copy it to your config directory:

   cp /etc/mango/config.conf ~/.config/mango/config.conf
   

   Or download a pre-configured setup:

   # Daily configuration
   git clone https://github.com/DreamMaoMao/mango-config.git ~/.config/mango
   
   # Or DMS configuration
   git clone -b dms https://github.com/DreamMaoMao/mango-config.git ~/.config/mango
   
3. Review basic settings

   Open ~/.config/mango/config.conf and review key settings:

   config.conf

   # Window effects
   blur=0
   shadows=0
   border_radius=6
   
   # Animations
   animations=1
   animation_duration_open=400
   animation_duration_close=800
   
   # Keyboard layout
   xkb_rules_layout=us
   
   # Appearance
   borderpx=4
   focuscolor=0xc9b890ff
   

Essential Tools

Mango is a compositor only - you’ll need additional tools for a complete desktop experience.

Recommended Setup

Minimal Setup

# Terminal emulator
yay -S foot

# Application launcher
yay -S rofi

# Wallpaper
yay -S swaybg

# Clipboard
yay -S wl-clipboard

Tool Categories

Terminal

foot, wezterm, alacritty, kitty, ghostty

Launcher

rofi, bemenu, wmenu, fuzzel

Status Bar

waybar (preferred), eww, quickshell, ags

Notifications

swaync, dunst, mako

First Launch

Now you’re ready to start Mango!

1. Launch from TTY

   From a TTY (Ctrl+Alt+F2), run:

   mango
   

   Or add to your display manager configuration.

2. Try default keybindings

   Window Management

   Alt+Return       - Open foot terminal
   Alt+Space        - Open rofi launcher
   Alt+Q            - Close window
   Alt+Arrow Keys   - Focus direction
   Alt+Backslash    - Toggle floating
   

   All keybindings can be customized in config.conf. Changes take effect after Super+R reload!

3. Customize your setup

   Edit ~/.config/mango/config.conf to:

   • Change keyboard layout: xkb_rules_layout=us
   • Enable effects: blur=1, shadows=1
   • Adjust animation speeds
   • Configure trackpad settings
   • Set your preferred colors

   Press Super+R to reload without restarting!

Quick Troubleshooting

Mango won't start

Check that you have all dependencies installed:

ldd $(which mango)

Verify wlroots version:

pkg-config --modversion wlroots-0.19

No keybindings working

Ensure your config file exists:

ls -la ~/.config/mango/config.conf

Check for syntax errors in your config.

XWayland apps not working

Ensure xwayland is installed:

which Xwayland

Mango requires xorg-xwayland package.

Visual effects not working

Verify scenefx is installed:

pkg-config --modversion scenefx-0.4

Check that effects are enabled in config:

blur=1
shadows=1

Next Steps

Configuration Guide

Deep dive into all configuration options

Keybindings

Learn all available commands and create custom bindings

Layouts

Explore different window layouts and their use cases

IPC & Scripting

Control Mango programmatically with IPC

Need Help?

Join our Discord community for support and discussions