Documentation — pudu Wayland compositor

Getting Started

It's early-stage and a solo hobby project, so bugs are part of the deal. Take it easy and file an issue if something breaks.

XWayland is not supported. pudu is a pure Wayland compositor.

Arch - Installation

Install with your favorite AUR helper:

yay -S pudu-git

Void - Installation

sudo xbps-install curl

curl -fsSL https://raw.githubusercontent.com/vodkanull/puduinstall/main/void.sh | sh

You don't need to run with sudo - the script will prompt for sudo when it needs to install packages, add groups, and enable services.

Debian/Fedora Installation

// Work in progress...

The binary will be placed at /usr/local/bin/pudu and the desktop entry at /usr/share/wayland-sessions/pudu.desktop.

When launching from TTY (without a display manager), just run:

pudu

Configuration

The configuration file is located at ~/.config/pudu/config. It uses a simple key-value syntax.

Mod Key

Set the mod key used for all bindings:

PUDU_MOD Super

Common values: Super (Windows key), Alt, Ctrl.

Autostart

Programs to launch when pudu starts:

autostart {
    # swaybg -i ~/wallpaper.jpg -m fill
    # waybar
    # mako
}

Keybinds

Keybinds are defined using the Super key (or whatever you set in PUDU_MOD).

Binding	Action
`Super` + `Enter`	Open terminal (default: kitty)
`Super` + `Left click` + drag	Move window
`Super` + `C`	Close focused window
`Super` + `R`	Reload config
`Super` + `Escape`	Exit pudu
`Super` + `←`	Previous workspace
`Super` + `→`	Next workspace
`Super` + `Shift` + `←`	Move window to previous workspace
`Super` + `Shift` + `→`	Move window to next workspace

Special Functions

These built-in actions can be assigned to keybinds in the binds block:

Function	Description
`PUDU_MOD`	Sets the modifier key (e.g., `Super`, `Alt`)
`PUDU_CLOSE`	Close the focused window
`PUDU_EXIT`	Exit the compositor
`PUDU_RELOAD`	Reload config (kills autostarts, reloads, re-runs autostarts)
`PUDU_WORKSPACE_PREV`	Switch to the previous workspace
`PUDU_WORKSPACE_NEXT`	Switch to the next workspace
`PUDU_WORKSPACE_MOVE_PREV`	Move focused window to the previous workspace
`PUDU_WORKSPACE_MOVE_NEXT`	Move focused window to the next workspace

Example usage in binds:

binds {
    Super+Return         kitty

    Super+r              PUDU_RELOAD
    Super+C              PUDU_CLOSE
    Super+Escape         PUDU_EXIT

    Super+Left           PUDU_WORKSPACE_PREV
    Super+Right          PUDU_WORKSPACE_NEXT
    Super+Shift+Left     PUDU_WORKSPACE_MOVE_PREV
    Super+Shift+Right    PUDU_WORKSPACE_MOVE_NEXT
}

UI Options

Example

ui {
    inner_gap           8
    outer_gap           8
    border_size         2
    border_radius       8
    border_active       #c574dd
    border_inactive     #3e304c
    border_transition   100
    new_is_master       false
    workspace_count     5
}

Option	Description
`inner_gap`	Gap between windows (px)
`outer_gap`	Gap around the screen edges (px)
`border_size`	Width of window borders (px)
`border_radius`	Window corner radius (px)
`border_active`	Border color for the active window
`border_inactive`	Border color for inactive windows
`border_transition`	Border color transition speed (ms)
`new_is_master`	New windows open as master
`workspace_count`	Number of workspaces

Input

input {
    natural_scroll      true
    # keyboard_layout    latam
}

Option	Description
`natural_scroll`	Enable natural (reverse) scrolling
`keyboard_layout`	Keyboard layout (e.g., `latam`, `us`)

Supported Wayland Protocols

Protocol	Description
`xdg-shell`	Standard window support
`wlr-layer-shell-unstable-v1`	Bars (Waybar), wallpapers (swaybg), etc.
`wlr-screencopy-v1`	Screenshots and single-frame capture
`wlr-export-dmabuf-v1`	Efficient video capture via DMA-BUF
`ext-session-lock-v1`	Secure session locking (e.g. swaylock)
`ext-workspace-v1`	Workspace-aware bars and taskbars
`wlr-pointer-constraints-v1`	Locking/confining the mouse pointer
`wlr-foreign-toplevel-management-v1`	Taskbars and window switchers
`wlr-xdg-output-v1`	Better multi-monitor support
`wlr-xdg-decoration-v1`	Window decorations
`wlr-data-control-v1`	Clipboard managers
`wlr-gamma-control-v1`	Gamma/LUT adjustments
`subcompositor`	Subsurface placement
`xdg-activation-v1`	Application startup and window activation
`ext-idle-notify-v1`	Idle inhibition and idle notification

Contributing

If you find a bug, have a suggestion, or just want to share your thoughts, feel free to open an issue on GitHub.

Pull requests are not accepted — this is a personal hobby project.

License

pudu is made in 🇨🇱 and is under the GPL v3.0 license.

See the LICENSE file for details.