dwm - dynamic window manager

dwm is an extremely fast, small, and dynamic window manager for X.

---

This is a Fedora-first X11 desktop environment built around a heavily modified version of dwm from suckless.org, a managed Quickshell shell, and supporting desktop services. Fedora Server Network Install is the primary image base; Debian-, Arch-, Fedora-, and RHEL-family existing-system installs retain the supported core desktop.

Patches & Features

• Quickshell panel and application launcher for the normal desktop workflow
• Settings foundation with searchable capability discovery and explicit unsupported-state reporting
• Window swallowing — terminals absorb child GUI windows
• EWMH compliance — proper desktop/tag reporting for external tools
• Pertag — independent layouts, master counts, and sizing per tag
• Cfact — per-window sizing in tiled layouts
• Movestack — reorder windows in the stack with keybinds
• Systray — built-in system tray
• Fullscreen — actual and fake fullscreen toggle (3-state)
• Window icons — title bar icons via _NET_WM_ICON
• Cursor warp — cursor follows focus across windows/monitors
• Noborder — auto-remove borders when only one window is visible
• Multi-monitor — Xinerama support with EWMH-aware tags

---

Install

Choose the path that matches what you are installing:

Path	Best for	Result
install.sh	Existing Debian-, Arch-, Fedora-, or RHEL-family system	Installs dependencies, builds dwm, installs the session, and preserves local config
Fedora ISO	Fresh Fedora install	Boots a Fedora installer with dwm-titus Kickstart and this repo embedded

Option 1: Install on an Existing System

git clone https://github.com/ChrisTitusTech/dwm-titus.git
cd dwm-titus

./install.sh --dry-run --non-interactive --profile recommended
./install.sh --profile recommended

Profiles:

Profile	Use when you want
core	dwm, required X11/session packages, and one terminal
recommended	core plus Quickshell, Picom, fonts, theming, screenshots, audio, and brightness tools
full	recommended plus optional extras such as Thunar with SMB-share browsing, portals, wallpapers, and display-manager setup; x86_64 Fedora can also add Steam, Gamescope, GameMode, and MangoHud after repository approval

The installer detects the distribution from /etc/os-release, resolves package names for the detected family, preserves existing config.h and user TOML files, and installs the managed Quickshell config. Upgrades also remove the legacy graphical-session enablement that could start XDG applications before the X11 display environment was imported. New installs add the dwm exclusion to matching vendor Picom, polkit, and Light Locker XDG entries while preserving their original commands and session guards. No override is created when the vendor entry is absent, and existing user entries remain untouched. Interactive installs running inside X11 also offer the dwm-display-setup wizard for persistent resolution, refresh rate, position, rotation, primary-display, and compatible TearFree configuration. If installation runs from a TTY, run the wizard after login.

On x86_64 Fedora, the full profile can enable the christitustech/copr-fedora COPR for the patched Gamescope package and RPM Fusion nonfree for Steam. These third-party repositories require a separate interactive confirmation or the explicit --enable-fedora-gaming-repos flag. After approval, the installer also installs both 64-bit and 32-bit GameMode and MangoHud libraries and adds the invoking user to the gamemode group. Log out and back in before expecting GameMode's privileged tuning helpers to work.

For unattended runs:

./install.sh --non-interactive --yes --profile recommended

# Explicitly approve Fedora gaming repositories for an unattended full install.
./install.sh --non-interactive --yes --profile full --enable-fedora-gaming-repos

Option 2: Install from the Fedora ISO

Download the latest installer image from the GitHub release:

ISO	Download
Standard	dwm-titus.iso
NVIDIA	dwm-titus-nvidia.iso
Checksums	latest release assets

Use the NVIDIA ISO when the machine needs the NVIDIA Kickstart and installer boot arguments. Otherwise use the standard ISO.

Basic flow:

1. Write the ISO to a USB drive.
2. Boot the machine from the USB drive.
3. Choose the Fedora install entry.
4. Complete the installer.
5. Reboot and select the dwm session if your display manager asks.

The ISO exposes the embedded checkout at /run/install/repo/dwm-titus during installation and uses the included Fedora Kickstart.

Starting dwm

With a display manager, log out, select the dwm session, and log back in.

With startx, run:

startx

After login, use these first:

Keybind	Action
SUPER + X	Open terminal
SUPER + R	Toggle Quickshell launcher
SUPER + F1	Open control center
SUPER + /	Open keybind viewer

Open Control Center -> Settings for the unified read-only capability overview, or run dwm-settings open from a terminal.

---

⌨️ Keybindings

Press SUPER + / inside dwm for an interactive keybind viewer.

See docs/src/keybinds.md for the full reference.

Essential Keybinds

Keybind	Action
SUPER + X	Open terminal
SUPER + R	Toggle Quickshell launcher
SUPER + Q	Close window
SUPER + J / K	Focus next / previous window
SUPER + H / L	Resize master area
SUPER + 1-9	Switch to tag (workspace)
SUPER + Shift + 1-9	Move window to tag
SUPER + 0	Show windows from all nine tags at once
SUPER + T	Tile layout
SUPER + F	Floating layout
SUPER + M	Fullscreen
SUPER + Space	Toggle floating
SUPER + Shift + Q	Quit dwm and cleanly end the graphical session
SUPER + Ctrl + Q	Power menu

---

🔧 Configuration

dwm is configured by editing config.h and recompiling:

$EDITOR config.h
make && sudo make install

Note: config.def.h is the tracked default template. config.h is ignored by Git and belongs to the local user. If it does not exist, make creates it from config.def.h; pulls and upgrades do not replace it. The installer creates it interactively on first installation, asking for stable compile-time preferences such as refresh rate, font size, modifier key, layout ratio, cursor warp, swallowing, and resize hints.

For unattended installation, the same values can be supplied with DWM_REFRESH_RATE, DWM_FONT_SIZE, DWM_MODKEY, DWM_MFACT, DWM_NMASTER, DWM_CURSORWARP, DWM_SWALLOWFLOATING, and DWM_RESIZEHINTS. Existing config.h files are always preserved.

Key things to customize in config.h:

• refresh_rate — match your monitor (default: 60, set to 120 for high-refresh)
• fonts[] — font family and size
• colors[] — color scheme (Nord theme by default in config.h)
• autostart[] — programs launched on startup
• rules[] — per-application window rules (floating, tags, terminal detection)
• keys[] — all keybindings
• MODKEY — modifier key (Mod4Mask = Super, Mod1Mask = Alt)

---

🔍 Troubleshooting

Black screen / dwm doesn't start:

• Run dwm-diagnostics and resolve any required X11/session failures.
• Preview required packages with ./install.sh --dry-run --profile core.
• Check .xinitrc exists and ends with exec dwm
• Try startx from a TTY to see error output

No status bar / Quickshell missing:

• Install the recommended desktop layer: ./install.sh --profile recommended
• Verify the managed shell config exists: ls ~/.config/quickshell/shell.qml
• Run manually: quickshell --no-duplicate

Restore the Picom configuration:

• The installer preserves the original system Picom configuration as /etc/xdg/picom.conf.dwm-titus.bak before excluding Quickshell from any translucent tooltip rule.
• Restore it with: sudo install -o root -g root -m 0644 /etc/xdg/picom.conf.dwm-titus.bak /etc/xdg/picom.conf
• Restart Picom or log out and back in after restoring it.

Terminal doesn't open (SUPER+X):

• Install a terminal emulator (alacritty, kitty, st, warp-terminal, or xterm)
• Or set DWM_TERMINAL / edit hotkeys.toml to use your preferred terminal
• Browser defaults: run dwm-default-apps browsers, then dwm-default-apps set-browser <desktop-id>
• Persistent display setup: run dwm-display-setup; use dwm-display-setup detect first to inspect outputs and TearFree support
• Display profiles: run dwm-display-profile template and save optional profiles under ~/.config/dwm-titus/display-profiles/
• Diagnostics: run dwm-diagnostics to separate required failures from optional degraded desktop features
• Full system snapshot: open Control Center -> System Health, or run dwm-system-health scan-user for the unprivileged structured report. The privileged scan uses cached or NOPASSWD sudo access first, then falls back to the running polkit agent and root-owned installed helper for graphical authorization.

Multi-monitor issues:

• If tags don't switch correctly across monitors, run dwm-diagnostics

Dependency check:

bash scripts/check-deps.sh

---

📁 Project Structure

Path	Purpose
config.def.h	Default configuration template
config.h	Generated, untracked personal configuration (edit this)
dwm.c	Main window manager source
Makefile	Build and install system
.xinitrc	Startup script for startx
dwm.desktop	Session entry for display managers
install.sh	Automated installer for Debian, Arch, and Fedora/RHEL families
config/	Quickshell, terminal, and app configurations
scripts/	Helper scripts (keybinds viewer, dep checker, etc.)
docs/src/keybinds.md	Full keybinding reference
CONTRIBUTING.md	Development and validation workflow
SECURITY.md	Private vulnerability reporting policy
CHANGELOG.md	User-facing release history
SPEC.md	Durable product scope and acceptance criteria
ROADMAP.md	Fedora-first desktop-environment phases
TASKS.md	Detailed work for the active roadmap phase
docs/RELEASING.md	Release validation and publication checklist

---

Development

Run the repository checks before submitting a change:

make check

This performs a clean portable build, ShellCheck and shfmt validation, autostart guard tests, staged install/uninstall checks, and release artifact validation. Use make native only for a binary intended for the current machine; normal builds remain portable across compatible CPUs.

Current implementation tasks are tracked in TASKS.md, phase outcomes in ROADMAP.md, and durable product requirements in SPEC.md.

Additional environment-specific gates are available:

make check-xvfb-runtime check-monitor-tags
make check-quickshell-qml
make check-container-smoke
mdbook build docs && mdbook test docs

See CONTRIBUTING.md for required validation by change type and SECURITY.md for private vulnerability reporting.