🐍 qtile-setup

A complete Qtile setup script for Debian-based systems. Features dynamic tiling layouts, powerful keybindings, a unified theme switcher, and a polished desktop experience — ready to roll out of the box.

Part of the JustAGuy Linux window manager collection — installable standalone or via butterknife, the installer for Butterbian.

📦 System Requirements

• Debian 12 (Bookworm) - Uses pipx installation method
• Debian 13 (Trixie) - Uses native qtile package from repository
• Ubuntu and other Debian-based systems - Uses pipx installation method

The installer automatically detects your system version and chooses the appropriate installation method.

Installation Method

The installer automatically chooses the best method based on your system:

Debian 13 (Trixie) and newer ✅ Recommended

• Uses the native qtile package from Debian repositories (v0.31.0)
• Simple and clean: sudo apt install qtile python3-psutil
• Stable and tested - Debian's rigorous testing ensures reliability
• All dependencies handled automatically by the package manager
• Integrates seamlessly with the system
• Better system integration than pipx installation
• Note: python3-psutil is required for CPU and memory monitoring widgets in the qtile bar

Debian 12 (Bookworm) and older

• Uses pipx to install Qtile 0.31.0 in an isolated environment
• Why pipx?
  • Qtile is not available in Debian 12 repositories
  • Provides access to qtile when system packages aren't available
  • Isolated environment prevents Python package conflicts
• Version Note: Installs Qtile 0.31.0 specifically as version 0.33+ has compatibility issues with Debian 12

Manual Installation Options

If you prefer to handle Qtile installation yourself:

# Debian 13+ (recommended - stable and well-tested)
sudo apt install qtile python3-psutil

# Debian 12 or if system package unavailable (use version 0.31.0)
pipx install qtile==0.31.0 && pipx inject qtile psutil

# Then run the installer with config-only mode
./install.sh --only-config

---

🚀 Quick Start

git clone https://justaguy.dev/drew/qtile-setup.git
cd qtile-setup
chmod +x install.sh
./install.sh

⚠️ XLibre users: This script installs xorg as part of its core packages, which will replace XLibre if you've installed it. Remove xorg from PACKAGES_CORE in install.sh before running, or use --only-config to skip package installation entirely.

Installation Options

./install.sh [OPTIONS]

Options:
  --only-config       Only copy config files (skip packages and external tools)
  --help              Show usage information

Advanced Usage Examples

# Update only configuration files (skip all package/tool installations)
./install.sh --only-config

---

📦 What It Installs

Core Components

Component	Purpose
qtile	Dynamic tiling window manager
python3-psutil	System monitoring for qtile bar
rofi	App launcher + power menu
dunst	Lightweight notifications
picom (yshui)	Compositor with transparency
thunar	File manager (+plugins)
kitty	Terminal emulator
firefox-esr	Default web browser
flameshot	Screenshot tool
pamixer	Audio control
feh	Wallpaper manager
xsettingsd	Live GTK theme updates
xfce4-power-manager	Power management
network-manager-gnome	Network management
micro	Terminal text editor
qimgv	Lightweight image viewer
exa/eza	Modern ls replacement

Themes & Fonts

Component	Purpose
Orchis Theme	GTK theme (all dark variants + Nord + Dracula)
Colloid Icons	Icon theme (all color schemes)
Nerd Fonts	Patched fonts with icons

---

🎨 Theme Switcher

Press Super + Shift + T to open the theme picker. Select a theme and your entire desktop switches instantly — qtile bar, wallpaper, notifications, launcher, terminal, GTK apps, and icons.

Available Themes (12)

Catppuccin, Doom One, Dracula, Everforest, GitHub Dark, Gruvbox, Gruvbox Dark, Kanagawa, Monokai, Moonfly, Nord, Retro

What Gets Switched

Component	Method	Live Refresh
Qtile (bar, borders)	Swaps color function in config.py, restarts qtile	Yes
Wallpaper	feh sets immediately, updates autostart.sh	Yes
Dunst (notifications)	Copies themed config, restarts dunst	Yes
Rofi (launcher/menus)	Copies themed .rasi files	Next launch
Kitty (terminal)	Applies theme via kitty +kitten themes, reloads all windows	Yes
GTK theme + icons	Updates settings.ini, restarts xsettingsd	Yes

Each theme has pre-generated template configs for dunst and rofi in themes/<name>/. Kitty uses its bundled iTerm2/Gogh color scheme collection. GTK live refresh is handled by xsettingsd.

See the Themes wiki page for full details on how the switcher works, the file structure, and how to add new themes.

💡 Special thanks to vinceliuice for the excellent GTK and icon themes.

---

🔑 Keybindings

Press Super + / to open the keybinding cheat sheet in rofi, grouped by category.

Launch

Shortcut	Action
Super + Enter	Launch terminal (kitty)
Super + Space	Launch Rofi
Super + /	Show keybindings
Super + B	Launch browser
Super + Shift + B	Launch Firefox (Private)
Super + F	Launch file manager
Super + E	Launch text editor
Super + D	Launch Discord
Super + G	Launch GIMP
Super + O	Launch OBS
Print / Super + S	Screenshot (full screen)
Super + Print / Super + Shift + S	Screenshot (region select)

Navigation

Shortcut	Action
Super + Arrow Keys	Move focus directionally
Super + J/K	Focus next/previous window
Alt + Tab	Cycle windows
Super + Shift + Arrow Keys	Move window directionally
Super + Shift + J/K	Move window up-left/down-right
Super + Ctrl + Arrow Keys	Resize window directionally
Super + 1–9,0,-,=	Switch to workspace (1-12)
Super + Shift + 1–9,0,-,=	Move window to workspace

Layout & Theming

Shortcut	Action
Super + Tab	Cycle through layouts
Super + Shift + L	Layout menu
Super + Shift + T	Theme switcher
Super + T	Toggle split direction in BSP
Super + Shift + Space	Toggle floating (centered 75%)
Super + Shift + Z	Reset all window sizes

Window Management

Shortcut	Action
Super + Q	Close focused window
Super + Shift + R	Restart Qtile
Super + Shift + Q	Exit Qtile
Super + X	Power menu

Media

Shortcut	Action
Super + F12	Volume up
Super + F11	Volume down
Super + F10	Mute/Unmute
Super + V	Toggle volume scratchpad

---

🖥️ Layouts

Cycle layouts with Super + Tab or pick one from the layout menu with Super + Shift + L.

• MonadTall — Classic master-stack
• BSP — Binary space partitioning
• Columns — Dynamic column layout (3 columns)
• Max — Fullscreen stacked windows
• Floating — Free window placement
• Zoomy — Zoom-focused layout

---

📂 Configuration Files

~/.config/qtile/
├── config.py                    # Main Qtile configuration
├── colors.py                    # Color scheme definitions (12 themes)
├── themes/                      # Pre-generated theme templates
│   ├── github_dark/
│   │   ├── dunstrc              # Dunst notification config
│   │   ├── config.rasi          # Rofi app launcher theme
│   │   ├── power.rasi           # Rofi power menu theme
│   │   └── keybinds.rasi        # Rofi keybinds display theme
│   ├── dracula/
│   │   └── ...
│   └── .../                     # (12 theme directories total)
├── dunst/dunstrc                # Active dunst config (swapped on theme switch)
├── rofi/
│   ├── config.rasi              # Active rofi config (swapped on theme switch)
│   ├── power.rasi               # Active power menu config
│   └── keybinds.rasi            # Active keybinds display config
├── picom/picom.conf             # Compositor configuration
├── wallpaper/                   # Wallpaper collection (one per theme)
└── scripts/
    ├── autostart.sh             # Startup: polkit, feh, picom, dunst, xsettingsd
    ├── thememenu                # Theme switcher script
    ├── help                     # Keybind cheat sheet (auto-parsed from config.py)
    ├── power                    # Rofi power menu
    ├── layoutmenu               # Rofi layout switcher
    └── changevolume             # Volume control with notifications

External configs modified by theme switcher:

~/.config/kitty/current-theme.conf  # written by the theme kitten
~/.config/gtk-3.0/settings.ini   # gtk-theme-name, gtk-icon-theme-name
~/.xsettingsd                    # Live GTK theme broadcasting

---

🔍 HiDPI / 4K Displays

Tiny type on a 4K screen? There's no single scaling knob — each toolkit (X fonts, GTK, Qt, the cursor) has to be told separately. Because qtile launches apps itself, the HiDPI block lives in ~/.config/qtile/config.py (commented, near the top), not in autostart.sh; uncomment it and restart qtile. Full walkthrough — 200% vs 150%, GTK/Qt/cursor, the bar — on the Troubleshooting wiki page under HiDPI / 4K displays.

---

🪟 Qtile Features

• Python Configuration: Full Python programming in your config — write functions, use conditionals, import modules
• 12 Color Themes: Switch your entire desktop with one keybinding via the unified theme switcher
• Context-Aware Functions: Smart resize/focus that adapts behavior based on current layout (BSP, Columns, MonadTall, Floating)
• Dynamic Layouts: 6 tiling algorithms with easy switching
• Waybar-Style Status Bar: 34px height with colored icons, centered clock, system monitoring
• Toggleable Clock: Click to switch between time and date display
• Smart Borders: Themed focused borders, 4px width, 10px gaps
• System Tray: Integrated system tray in the status bar
• Workspace Management: 12 workspaces with intuitive navigation and window rules
• Auto-floating: Certain windows automatically float (dialogs, pavucontrol, etc.)
• Scratchpad Dropdowns: Terminal and volume mixer dropdowns
• Notifications: Desktop notifications via dunst with volume/layout/theme feedback
• Self-Parsing Help: Keybinding cheat sheet auto-generated from config.py, grouped by category

---

License

GPL-2.0 - See LICENSE for details.

Support

Connect

• YouTube — tutorials and guides
• Butterforge — source code and projects
• The Butter Lab — Discourse forum
• The Churn — community chat (Fluxer)
• Wiki — documentation and guides
• Mastodon — @justaguylinux@fosstodon.org
• Butterbian — a Debian-based distro

---

Made with butter by JustAGuyLinux