bitzdots
gitlabLean Hyprland dotfiles with automatic matugen theming. Low-end optimized, full-stack auto-coloring, 26 Jinja2 templates. Rofi-powered menus, waybar modules, screenshot/recording, event-driven cache daemon.
clone
https://gitlab.com/bitzzdev/bitzdots.gitarchlinuxdotfileshyprlandhyprland-dotfileslow-endminimalricingwallustwaybarwayland
# Frequently Asked Questions## General### What makes bitzdots different from other Hyprland dotfiles?- **Low-end first** — Every component is optimized for minimal CPU and RAM usage- **Full-stack auto-theming** — 25 Jinja2 templates propagate wallpaper colors to 20+ components- **Event-driven cache daemon** — Wallpaper cache pre-generates in background so switching is instant- **Safe by design** — Every theme generation backs up files and restores on failure- **No bloat** — Every script and dependency earns its place### What hardware does it support?Any system that runs Hyprland. Optimized for low-end devices with 2-4GB RAM. The full desktop stack (Hyprland + waybar + swaync) idles under 300MB.### Which distros are supported?Arch Linux (including Arch-based), Fedora, Debian/Ubuntu, and NixOS. The installer auto-detects your distro.### Do I need a GPU?Hyprland requires a GPU with basic Vulkan support. Most integrated GPUs from 2012+ work.## Installation### The installer fails with "distro not supported"The installer supports Arch, Fedora, Debian/Ubuntu, and NixOS. For other distros:1. Install the packages manually (see [Installation](installation.md))2. Link the config files manually### Do I need to install packages manually?No — use `./install.sh --with-deps` to auto-install everything. Without the flag, only configs are linked.### I already have some of these tools configuredThe installer creates symlinks. Your existing configs won't be touched unless they share the same filename.## Theming### Theme doesn't update after changing wallpaper```bash# Manually run themingmatugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml~/.config/matugen/reload-theme.sh```### Colors look wrong on my wallpaperSome images give poor color extraction. Try:- Use a photo with more color variety- Convert to PNG- Manually adjust generated configsThe cache daemon has a 24-hour cooldown for problematic images.### Theme generation fails or takes too longIf `matugen image` takes over 30 seconds or errors with "Not enough colors!", the `kmeans` backend is struggling with the image. bitzdots defaults to the much faster `fastresize` backend (seconds, not minutes).```bash# Verify the backend is setgrep backend ~/.config/matugen/config.toml # Should say "fastresize"# Or force it for a one-off runmatugen image ~/Pictures/Wallpapers/image.jpg --config ~/.config/matugen/config.toml```### Apps not using dark themebitzdots defaults to dark theme for all apps. If something isn't dark:**GTK apps:**```bash# Check GTK settingscat ~/.config/gtk-3.0/settings.ini# Should contain:# gtk-theme-name=Adwaita# gtk-application-prefer-dark-theme=1# gtk-icon-theme-name=Papirus-Dark# Force GTK3/GTK4 dark modegsettings set org.gnome.desktop.interface color-scheme prefer-darkgsettings set org.gnome.desktop.interface gtk-theme Adwaita```**Qt apps:**```bash# Verify environmentecho $QT_QPA_PLATFORMTHEME # Should be "qt6ct"# QT_STYLE_OVERRIDE must be UNSET (empty). If set, remove it:unset QT_STYLE_OVERRIDE # and remove from hypr/variables.lua / environment.d# Check qt5ct configcat ~/.config/qt5ct/qt5ct.conf# Should have: style=Breeze-Dark, icon_theme=Papirus-Dark# Check qt6ct config (auto-generated by matugen)cat ~/.config/qt6ct/qt6ct.conf# Should have: style=Breeze-Dark, custom_palette=true```If qt6ct warns *"Please remove the QT_STYLE_OVERRIDE environment variable"*,the variable is still set (commonly from an old session or `hypr/variables.lua`).Unset it and log out/in (or restart the Hyprland session) to re-export env vars.## Waybar### Waybar is not showing```bash# Start it manuallywaybar &# Check for errorsjournalctl --user -u waybar -f```### A waybar module shows no outputCheck the script runs independently:```bash~/.config/waybar/scripts/workspaces.sh```Common issues:- Script not executable: `chmod +x script.sh`- Missing dependency: check the script's requirements- Poll interval too long: reduce `interval` in config.jsonc### Media module shows "No player"A media player must be running and exposing MPRIS controls:- Spotify, Firefox (YouTube), VLC, etc.- Check with `playerctl -l`### Workspace module shows wrong workspacesThe workspace script uses `hyprctl workspaces -j`. Verify:```bashhyprctl workspaces```## Screenshots & Recording### Screenshot saves but isn't in clipboardBoth Print and SUPER+SHIFT+S save to file AND copy to clipboard via `wl-copy`. If clipboard is empty:- Ensure `wl-clipboard` is installed- Try pasting with Ctrl+V or middle-click### Screen recording doesn't include audioEnsure `wf-recorder` is installed with pulse support:```bash# Archsudo pacman -S wf-recorder# Check audio sourcepactl list short sources```## Performance### CPU usage is highCheck for common issues:```bash# Stale playerctl processespkill -f "playerctl metadata --follow"# Check powerprofilesctl (should not be running — uses busctl instead)pgrep powerprofilesctl# View CPU by processps aux --sort=-%cpu | head -10```### RAM usage is higher than expected```bash# Check per-process memoryps aux --sort=-%mem | head -15# Common memory hogs# - kitty: ~200MB per window (GPU-accelerated)# - Browser: 200MB+ per process# - swaync: ~85MB (album art caching)```### Waybar uses high CPU```bash# Check polling intervals (see performance.md)cat ~/.config/waybar/config.jsonc | grep interval# Most common culprit: workspaces.sh at high frequency# Current: 3s — increase to 5s or 10s```## Cache Daemon### Daemon status check```bashsystemctl --user status matugen-cache-daemon.servicejournalctl --user -u matugen-cache-daemon.service -f```### Daemon uses high CPUThe daemon runs at Nice=19 (lowest priority). If it uses CPU:- It's actively processing wallpapers (normal during initial cache)- After initial cache, it sleeps waiting for inotify events- Check logs: `journalctl --user -u matugen-cache-daemon.service`### Wallpaper palette generation failsLogs show failures:```bashjournalctl --user -u matugen-cache-daemon.service | grep -i "fail\|error"```Common causes:- Image format not supported by matugen- Image file is corrupted- 24-hour cooldown active from previous failure## General Troubleshooting### SwayNC not showing notifications```bash# Restart swayncswaync-client --reload-cssswaync-client -R # Reload configswaync-client -t # Toggle panel# Or fully restartpkill swaync && swaync &```### Rofi not themedEnsure `theme-generated.rasi` exists:```bashls -la ~/.config/rofi/theme-generated.rasi# If missing, regenerate theme:matugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml```### High CPU usage from xdg-desktop-portal-hyprland`xdg-desktop-portal-hyprland` can enter a CPU loop (90%+) in version 1.4.x. This is a known upstream issue.```bash# Fix: restart the portal servicesystemctl --user restart xdg-desktop-portal-hyprland```The install script does this automatically at the end of installation.### Inconsistencies after theme change```bash# Full theme refreshmatugen image ~/.cache/current_wallpaper.png --config ~/.config/matugen/config.toml~/.config/matugen/reload-theme.shpkill -x waybar && waybar &```### My changes keep getting overwrittenConfigs marked "DO NOT EDIT" are auto-generated by matugen on every theme change. To make permanent changes:- Edit the Jinja2 templates in `~/.config/matugen/templates/`- Re-run matugen to apply- See [Customization](customization.md)