Skip to content

faq.md

Latest commit

 

History

History
281 lines (196 loc) · 7.48 KB

faq.md

File metadata and controls

281 lines (196 loc) · 7.48 KB
Raw

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)
  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 configured

The installer creates symlinks. Your existing configs won't be touched unless they share the same filename.

Theming

Theme doesn't update after changing wallpaper

# Manually run theming
wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust
~/.config/wallust/reload-theme.sh

Colors look wrong on my wallpaper

Some images give poor color extraction. Try:

  • Use a photo with more color variety
  • Convert to PNG
  • Manually adjust generated configs

The cache daemon has a 24-hour cooldown for problematic images.

Theme generation fails or takes too long

If wallust run 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).

# Verify the backend is set
grep backend ~/.config/wallust/wallust.toml   # Should say "fastresize"

# Or force it for a one-off run
wallust run ~/Pictures/Wallpapers/image.jpg --config-dir ~/.config/wallust --backend fastresize

Apps not using dark theme

bitzdots defaults to dark theme for all apps. If something isn't dark:

GTK apps:

# Check GTK settings
cat ~/.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 mode
gsettings set org.gnome.desktop.interface color-scheme prefer-dark
gsettings set org.gnome.desktop.interface gtk-theme Adwaita

Qt apps:

# Verify environment
echo $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 config
cat ~/.config/qt5ct/qt5ct.conf
# Should have: style=Breeze-Dark, icon_theme=Papirus-Dark

# Check qt6ct config (auto-generated by wallust)
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

# Start it manually
waybar &

# Check for errors
journalctl --user -u waybar -f

A waybar module shows no output

Check the script runs independently:

~/.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 workspaces

The workspace script uses hyprctl workspaces -j. Verify:

hyprctl workspaces

Screenshots & Recording

Screenshot saves but isn't in clipboard

Both 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 audio

Ensure wf-recorder is installed with pulse support:

# Arch
sudo pacman -S wf-recorder

# Check audio source
pactl list short sources

Performance

CPU usage is high

Check for common issues:

# Stale playerctl processes
pkill -f "playerctl metadata --follow"

# Check powerprofilesctl (should not be running — uses busctl instead)
pgrep powerprofilesctl

# View CPU by process
ps aux --sort=-%cpu | head -10

RAM usage is higher than expected

# Check per-process memory
ps 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

# 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

systemctl --user status wallust-cache-daemon.service
journalctl --user -u wallust-cache-daemon.service -f

Daemon uses high CPU

The 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 wallust-cache-daemon.service

Wallpaper palette generation fails

Logs show failures:

journalctl --user -u wallust-cache-daemon.service | grep -i "fail\|error"

Common causes:

  • Image format not supported by wallust
  • Image file is corrupted
  • 24-hour cooldown active from previous failure

General Troubleshooting

SwayNC not showing notifications

# Restart swaync
swaync-client --reload-css
swaync-client -R  # Reload config
swaync-client -t  # Toggle panel

# Or fully restart
pkill swaync && swaync &

Rofi not themed

Ensure theme-generated.rasi exists:

ls -la ~/.config/rofi/theme-generated.rasi
# If missing, regenerate theme:
wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust

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.

# Fix: restart the portal service
systemctl --user restart xdg-desktop-portal-hyprland

The install script does this automatically at the end of installation.

Inconsistencies after theme change

# Full theme refresh
wallust run ~/.cache/current_wallpaper.png --config-dir ~/.config/wallust
~/.config/wallust/reload-theme.sh
pkill -x waybar && waybar &

My changes keep getting overwritten

Configs marked "DO NOT EDIT" are auto-generated by wallust on every theme change. To make permanent changes:

  • Edit the Jinja2 templates in ~/.config/wallust/templates/
  • Re-run wallust to apply
  • See Customization