Frequently Asked Questions

WifeRice is a complete Hyprland desktop environment configuration for Arch Linux. It features a custom QuickShell-based UI with a top bar, floating sidebar, 15+ popup widgets (battery, volume, network, Bluetooth, clipboard, music, calendar, weather, app launcher, and more), dynamic Matugen theming that adapts to your wallpaper, a beautiful lock screen with music player, SDDM login theme, wallpaper collection with a picker UI, and an automated installer that handles everything from GPU drivers to systemd services. The entire desktop is designed around a deep purple amethyst noir aesthetic.

No. The installer asks what to preserve before making any changes. It prompts: keybinds & shortcuts, terminal & editor (Kitty, Neovim), desktop configs (Rofi, SwayNC, Matugen), and wallpapers. It also asks if you want to override the SDDM theme and optionally lets you configure weather API. Whatever you choose to keep is left untouched. Your settings.json (monitor layout, startup apps, custom keybinds) is never touched. The only files overwritten are the QuickShell QML files, scripts, and config templates — everything you'd want updated. Weather .env and ~/.Wallpapers/ survive every update.

Yes. The one-liner installer works on both fresh and existing Arch systems. It detects what's already installed and only adds missing packages via pacman and yay. Your existing files in ~/Pictures/Wallpapers/, ~/.Wallpapers/, and ~/.config/hypr/settings.json are preserved. The installer also detects your GPU (NVIDIA, AMD, or Intel) and installs the appropriate drivers if missing. Note: this is designed for Arch Linux and arch-based distros only. For EndeavourOS or Manjaro, see "Can I install this on EndeavourOS or Manjaro?" below.

Three GPU families are supported:

NVIDIA — proprietary drivers (nvidia nvidia-utils nvidia-settings lib32-nvidia-utils). The installer handles NVIDIA Optimus laptops with PRIME configuration.

AMD — open-source mesa/amdgpu (mesa lib32-mesa xf86-video-amdgpu vulkan-radeon lib32-vulkan-radeon). Works out of the box.

Intel — open-source mesa (mesa lib32-mesa vulkan-intel lib32-vulkan-intel). Works out of the box.

The installer detects your GPU during step 3 and installs the appropriate drivers automatically. If you have both an integrated and discrete GPU (e.g., Intel + NVIDIA), the installer configures PRIME for you.

Three ways:

1. Automatic notification — The update notifier daemon checks for new versions every 10 minutes. When a new version is detected, a notification appears in the top bar. Click it to run the installer.

2. Manual one-liner — Run the same install command: bash -c "$(curl -fsSL https://raw.githubusercontent.com/eprahemi/WifeRice/main/install.sh)"

3. Via Guide — Press Super+H, go to the Recent Changes tab. If an update is available, click the update button.

All methods are safe — they preserve your settings and ask what to keep. After updating, check the changelog tab (Super+H) or the website changelog to see what changed.

QuickShell is a Qt Quick-based shell environment for Hyprland. Think of it like a lightweight desktop shell — it replaces panels, docks, and widgets with QML-based UIs that render directly on the GPU. WifeRice runs three QuickShell instances:

Main.qml — The overlay that hosts all popup widgets (battery, volume, network, Bluetooth, clipboard, calendar, app launcher, notifications, etc.).

TopBar.qml — A multi-monitor horizontal bar with workspaces, clock, system tray, volume slider, battery indicator, network status, and keyboard layout.

Floating.qml — A right-edge floating sidebar with quick actions and system stats.

Lock.qml — A full-screen lock screen with clock, music player, and PAM authentication.

Unlike conventional panels (Waybar, Polybar), QuickShell QML components can animate, blend, and interact like a modern app. It's the same technology KDE Plasma uses under the hood.

Drop any image file into ~/.Wallpapers/ with the name lock.* (e.g., lock.png, lock.jpg, lock.webp). The lock script detects it automatically. Priority order: ~/.Wallpapers/lock.* (user custom, highest priority) → /usr/share/wallpapers/lock.png (system default, overwritten on install). If you want the lock screen to match your desktop wallpaper, just open the wallpaper picker (Super+W) and set your wallpaper — the lock screen follows. For the SDDM login screen wallpaper, see "The SDDM theme doesn't show up" below.

The installer asks if you want to configure weather during setup. If you skipped it or want to change it:

1. Get a free API key at openweathermap.org (free tier allows 60 calls/minute)
2. Find your city ID at openweathermap.org/find
3. Edit ~/.config/hypr/scripts/quickshell/calendar/.env:

WEATHER_API_KEY=your_key_here
CITY_ID=your_city_id
WEATHER_UNIT=metric (or imperial)

4. Reload QuickShell: Super+R

The .env file is preserved during updates — it has chmod 600 permissions and is explicitly excluded from the rsync deploy.

The picker prunes orphan thumbnails automatically every time you open it. If you still see stale or broken entries:

Clear color markers only:
rm -rf ~/.cache/wallpaper_picker/colors_markers/*

Rebuild everything from scratch:
rm -rf ~/.cache/wallpaper_picker/

New thumbnails regenerate on next picker open. The first load may take a few seconds depending on how many wallpapers you have. Thumbnails are cached as WebP (256px wide) for fast loading on subsequent opens. The color markers store dominant color info used by the filter buttons (Red, Orange, Yellow, Green, Blue, Purple, Pink, Monochrome, Video, All).

Edit ~/.config/hypr/settings.json and change the "language" field. For example, "us,ara" gives you US English with Arabic as a second layout. Multiple layouts can be comma-separated. After saving:

Method 1: Run settings_watcher.sh --compile to regenerate configs immediately.

Method 2: Wait for auto-detection — the settings watcher monitors changes to settings.json and recompiles within a few seconds.

Method 3: Use the Settings panel — Super+Shift+S opens the GUI settings editor.

The keyboard layout indicator in the top bar updates in real time. You can cycle through layouts with a click on the indicator or by binding a key in settings.json.

Two ways:

In-app (recommended): Press Super+H to open the Guide, go to the Report tab, select the category and severity, provide details, and send. The report automatically includes your system info (CPU, GPU, RAM, kernel version, Hyprland version, QuickShell version) and is sent via Discord webhook so the developer gets notified immediately.

GitHub Issues: Open an issue at github.com/eprahemi/WifeRice/issues. Please include your system info and steps to reproduce.

Either way, screenshots and logs help a lot. Check ~/.config/hypr/hyprland.log and journalctl -xe for relevant error messages.

Bluetooth should work out of the box after installation. If it doesn't:

1. Check if the service is running: systemctl status bluetooth
2. Enable and start it: sudo systemctl enable --now bluetooth
3. Make sure your Bluetooth adapter is detected: bluetoothctl list
4. Open the Bluetooth popup from the network widget in the top bar, or press Super+N to open the network popup which includes Bluetooth controls.

Troubleshooting: If your adapter isn't detected, you may need firmware (sudo pacman -S linux-firmware). Some Realtek and Broadcom adapters need additional drivers. Run dmesg | grep -i bluetooth to see kernel messages. For audio over Bluetooth (headphones/speakers), the installer includes pipewire-ffado and libldac for high-quality AAC and LDAC codec support.

The WifeRice volume popup supports a 150% boost mode. When your volume slider is at 100% and still too quiet:

1. Open the volume popup (Super+X)
2. Continue dragging the slider above 100% — it goes up to 150%
3. Or click the boost icon to toggle between normal and boosted ranges

This works by setting PipeWire's volume above 1.0 using wpctl. If you need even more volume, check your application's internal volume, your speaker/headphone hardware volume, and try running pavucontrol (Super+V) to check individual sink volumes. Also check if your audio profile is set correctly — some USB headsets default to "HiFi" profile which limits volume range.

Just drop images into ~/Pictures/Wallpapers/. The wallpaper picker (Super+W) scans this directory automatically on open. Supported formats: PNG, JPG, JPEG, WEBP, BMP, GIF (static). For video wallpapers, place MP4 files in the same directory and the picker will detect them (requires mpvpaper which the installer sets up). The picker pre-generates thumbnails for instant loading — your first open after adding new images may take a moment. You can filter wallpapers by dominant color using the buttons at the top. Wallpapers in ~/Pictures/Wallpapers/ are never touched by the installer.

The top bar is defined in ~/.config/hypr/scripts/quickshell/TopBar.qml. You can edit this QML file directly to add, remove, or rearrange widgets. Common customizations:

Change bar height: Look for the height property in the root Rectangle (default is around 40px).

Add a clock format: Modify the clock text item to use a different date format string.

Hide system tray: Comment out or remove the SystemTray component.

Reorder elements: Just move the child items around in the layout.

Custom colors: The bar uses MatugenColors.qml and qs_colors.json — update the JSON to change the default palette. Colors adapt to your wallpaper automatically via Matugen, but you can override specific colors in the JSON file.

Note: The bar is overwritten on every update. If you make custom changes, back up your TopBar.qml or be prepared to reapply them after updates.

Yes. The default terminal is Kitty, but you can switch to any terminal by editing ~/.config/hypr/config/variables.conf. Change $terminal = kitty to your preferred terminal command (e.g., $terminal = alacritty, $terminal = wezterm, $terminal = foot, $terminal = konsole). The change applies to Super+T (open terminal) and all other terminal-launching keybinds. Your config files won't be overwritten on update since they're in the template-generated section. Some QML components that embed terminal previews may still show Kitty — you'd need to modify the relevant QML files for those.

First, don't panic. Here's the recovery path:

1. Reload QuickShell: Press Super+R to reload all QuickShell instances. This fixes most visual glitches.

2. Check the logs: Run journalctl --user -u quickshell-main -u quickshell-topbar -u quickshell-floating to see QuickShell errors. Also check ~/.config/hypr/hyprland.log for Hyprland issues.

3. Re-run the installer: The installer is idempotent — running it again won't hurt. It will re-deploy all files fresh.

4. Rebuild configs: Run settings_watcher.sh --compile to regenerate all Hyprland configs from templates.

5. Check settings.json: Make sure your settings file is valid JSON. A syntax error can cause the settings watcher to fail.

6. Fall back: If nothing works, report the bug (Super+H → Report tab) with your system info. The developer usually responds quickly.

WARNING: This removes your entire desktop configuration. Back up what you want to keep first.

Remove config files:
rm -rf ~/.config/hypr
rm -rf ~/.config/quickshell
rm -rf ~/.config/kitty
rm -rf ~/.config/neofetch
rm -rf ~/.config/rofi

Remove QuickShell:
sudo pacman -Rns quickshell
yay -Rns quickshell-git # if installed from AUR

Remove installed packages (optional): The installer installs many packages. Check ~/.config/hypr/scripts/install.sh for the full list if you want to remove selectively.

Remove wallpapers (optional):
rm -rf ~/Pictures/Wallpapers
rm -rf ~/.Wallpapers

Reset to default Hyprland config: If you just want to remove the WifeRice config and start fresh, delete ~/.config/hypr/ and let Hyprland generate its default config when you next log in.

This usually means SDDM isn't configured to use the theme, or the theme wasn't deployed correctly. Fix it:

1. Check that the theme exists: ls /usr/share/sddm/themes/matugen-minimal/
2. If missing, re-run the installer — it deploys the theme in step 16.
3. Edit SDDM config: sudo nano /etc/sddm.conf
4. Set the theme:

[Theme]
Current=matugen-minimal

5. If you want the SDDM wallpaper to match your lock screen, replace /usr/share/wallpapers/lock.png with your desired image.
6. Reboot to see the theme: systemctl reboot

Troubleshooting: If SDDM still shows the default theme, check /usr/lib/sddm/sddm.conf.d/ for config files that might override /etc/sddm.conf. The installer also sets qt5ct and qt6ct environment variables in /etc/environment for consistent Qt theming across SDDM and the desktop.

The lock screen music player scans ~/.config/hypr/scripts/quickshell/music/ for MP3 files. Just copy your music there:

cp /path/to/your/*.mp3 ~/.config/hypr/scripts/quickshell/music/

Supported format: MP3. The player uses pw-play under the hood for playback. It reads music_control.sh which handles playlist management and next/previous/pause controls from the lock screen. The music no longer auto-plays on lock — press the play button to start. To customize the player appearance, edit ~/.config/hypr/scripts/quickshell/Lock.qml (but note this file is overwritten on updates — back up your changes).

Technically yes, but it's not recommended. The QuickShell top bar is tightly integrated with the rest of the desktop — the system tray, workspace indicators, and popup triggers all expect the TopBar QML instance to be running. The popup widgets (battery, volume, network, etc.) are positioned relative to the bar. If you disable the QuickShell bar, you'll lose:

• Workspace indicator with window thumbnails
• Clock and date
• System tray (tray icons from Discord, Steam, etc.)
• Volume slider
• Battery indicator with percentage
• Network/Bluetooth status
• Popup trigger points (clicking bar elements opens the popups)

If you still want Waybar, you can run it alongside QuickShell by editing the autostart config. But consider that QuickShell's bar is one of the key features of WifeRice — it's GPU-accelerated, themeable, and responsive. Give it a try for a few days before switching.

Contributions are welcome! Ways to help:

Report bugs: Use Super+H → Report tab, or open a GitHub issue. Include system info and steps to reproduce.

Suggest features: Open a GitHub issue with the "enhancement" tag. Feature requests are tracked and reviewed.

Submit code: Fork the repo at github.com/eprahemi/WifeRice, make your changes, and submit a pull request. Please follow the existing code style and update the changelog.

Improve documentation: Spelling fixes, better explanations, translation help — all appreciated.

Share screenshots: Show off your WifeRice setup on Discord or tag the repo. Seeing setups in the wild helps motivate development.

Before contributing, review the AI protocol in .ai/update-protocol.md of the repo — it documents the golden rules for safe updates.

The screenshot tool saves images to ~/Pictures/Screenshots/ by default. If screenshots aren't working:

1. Check the directory exists: ls ~/Pictures/Screenshots. If not, create it: mkdir -p ~/Pictures/Screenshots
2. Check if grim and slurp are installed: which grim slurp. The installer should have included them; re-run if missing.
3. Test manually: grim ~/Pictures/Screenshots/test.png
4. For region select: run grim -g "$(slurp)" ~/Pictures/Screenshots/region.png
5. Check if swappy is installed (for the editor mode): which swappy
6. For the in-edit mode (Shift+Print), make sure satty or swappy is available as the editor.

Screenshot keybinds: Print = region + edit, Shift+Print = region skip editor, Super+Print = full screen, Super+Shift+Print = full screen + edit.

If nothing works, check journalctl --user -u quickshell-main for errors from the screenshot script.

The installer and health monitors collect basic telemetry (OS, kernel, GPU, install success/failure, disk usage, battery stats) to help debug issues and monitor system health. To disable it:

During install: The telemetry is compiled into the installer as base64 scripts that run after setup. They send data to Discord webhooks.

After install: Telemetry is handled by several scripts deployed to ~/.config/hypr/scripts/: check_battery.sh, check_version.sh, check_disk.sh, check_nvidia.sh, check_packages.sh, check_config.sh, check_network.sh, and check_qs_alive.sh. To disable, stop the health timers: systemctl --user disable --now qs-*.timer and remove the timer files from ~/.config/systemd/user/.

What's collected per script: OS/kernel/GPU info, version staleness, disk usage, battery health, NVIDIA driver status, package errors, config parse errors, network info, and QuickShell process health. No personal data, no files, no keystrokes.

Where it goes: Each script sends to its own Discord webhook. The source (base64) is embedded in install.sh and decoded during install. All scripts are open source in the repo.

WifeRice is designed for and tested on Arch Linux. It should work on EndeavourOS since it's essentially Arch with a GUI installer. For Manjaro, compatibility is not guaranteed for these reasons:

• Manjaro holds packages back for stability testing — Hyprland and QuickShell versions may be outdated
• Manjaro uses a different kernel management system
• The AUR helper detection (yay vs pamac) may behave differently
• Some dependencies may have different package names or be in different repos

If you want to try on Manjaro:
1. Install yay manually first
2. Enable AUR in pamac
3. Make sure you have the latest kernel
4. Run the installer and report any issues

The installer checks for Arch at the beginning and warns if it detects a non-arch distro but continues anyway. EndeavourOS users have reported successful installs. Manjaro users should expect to do some manual troubleshooting.

Audio auto-switch is a systemd service that detects when you plug in or unplug headphones and Bluetooth audio devices, then automatically switches the audio sink. It's enabled by default after installation. To check its status:

systemctl --user status audio-autoswitch

To manually toggle it:

systemctl --user start audio-autoswitch # Start
systemctl --user stop audio-autoswitch # Stop
systemctl --user enable audio-autoswitch # Enable on boot
systemctl --user disable audio-autoswitch # Disable on boot

The service runs ~/.config/hypr/scripts/watchers/audio_autoswitch.sh. It monitors udev events and Bluetooth device changes. When a new audio sink appears, it sets it as the default. When the sink disappears, it falls back to the previous one. This works with wired headphones, USB headsets, and Bluetooth speakers/headphones. No configuration needed — just plug in and it works.