11 KiB
Table of Contents
{{< toc format=html >}}
Nothing renders / screen is empty / crash on opening first app
Possible causes:
Your themes are not set up properly, making apps crash.
Use something like qt6ct
(QT) and nwg-look
(GTK) (*for GTK you can also
set up themes with envvars) to set up your themes.
Your PC is very, very old.
In that case, see the Installation Page and try compiling with LEGACY_RENDERER
For more info about bugs and crashes, see this wiki page
Me cursor no render?
Are you on NVIDIA? If so, then you have been a naughty boy and haven't listened
to my tips on other pages. Use the WLR_NO_HARDWARE_CURSORS=1
environment
variable.
My external monitor is blank / doesn't render / receives no signal (laptop)
For Radeon graphics - unfortunately, it's a bug in wlroots. You can either revert one commit from wlroots or use a special env flag, see https://gitlab.freedesktop.org/wlroots/wlroots/-/issues/3451
For Nvidia graphics - This issue appears to be resolved when using Nvidia Drivers 525.60.11 or later, but it may persist with older drivers.
Outside those, there is a way to fix it that might work for you though:
Option 1: Use only the external monitor
By using WLR_DRM_DEVICES=/dev/dri/card1
(or card0
) you can force Hyprland to use only your dGPU,
meaning your laptop's screen will be gone but your external one will work.
Option 2: Use all outputs, at the cost of battery life.
By switching your laptop to only use the dGPU in the BIOS, you might be able to get everything to work, at the cost of high battery usage.
Please note these are highly model-specific and might or might not work. If they don't, you're unfortunately out of luck.
You might try a USB-C to HDMI adapter though, maybe that could route the external monitor through the iGPU.
How do I screenshot?
Install grim
and slurp
Use a keybind (or execute) grim -g "$(slurp)"
, select a region. A screenshot
will pop into your ~/Pictures/
(You can configure grim and slurp, see their
GitHub pages).
For a more complete utility, try our own screenshotting utility: Grimblast.
For recording videos, wf-recorder, wl-screenrec or OBS Studio could be used.
Screenshare / OBS no worky
Check Screensharing.
Also install qt6-wayland
if you plan to use obs.
How do I change my wallpaper?
See Wallpapers.
My games work poorly, especially proton ones
Use gamescope
, tends to fix any and all issues with wayland/Hyprland.
How heavy is this?
Not that much heavier than Xorg. If you want maximum performance, consider turning off the blur and animations.
My monitor no worky
Try changing the mode in your config. If your preferred one doesn't work, try a
lower one. A good way to list all modes is to get wlr-randr
and do a
wlr-randr --dryrun
My monitor has flickering brightness when I turn on VRR
Change the VRR option to 2
(fullscreen), so that it is only used in games.
This happens because the brightness on some monitors can depends on the refresh
rate, and rapidly changing refresh rates (for example, when the screen momentarily
updates after pressing a key) will cause rapid changes in brightness.
How do I update?
Open a terminal where you cloned the repo.
git pull
sudo make clear
sudo make install
If you are using the AUR (hyprland-git) package, you will need to cleanbuild to update the package. Paru has been problematic with updating before, use Yay.
How do I screen lock?
Use a wayland-compatible locking utility using WLR protocols, e.g. swaylock
.
How do I change me mouse cursor?
- Set the GTK cursor using nwg-look.
- Add
exec-once=hyprctl setcursor [THEME] [SIZE]
to your config and restart Hyprland.
If using flatpak, run flatpak override --env=~/.themes:ro --env=~/.icons:ro --user
and put your themes in both /usr/share/themes
and ~/.themes
, and put your icons and cursors in both /usr/share/icons
and ~/.icons
.
For QT applications, Hyprland exports XCURSOR_SIZE as 24, which is the default.
You can overwrite this by exporting XCURSOR_SIZE to a different value with env
.
You can also try running gsettings set org.gnome.desktop.interface cursor-theme 'theme-name'
or adding it after exec-once=
in your config.
If you do not want to install a GTK settings editor, change the config files according to the
XDG specification (Arch Wiki link).
Make sure to also edit ~/.config/gtk-4.0/settings.ini
and ~/.gtkrc-2.0
if not using a tool
(like nwg-look
).
GTK Settings no work / whatever
https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland
My [program name] is freezing
Make sure you have a notification daemon running, for example dunst
. Autostart
it with the exec-once
keyword.
Waybar workspaces no worky???
Waybar has a set of caveats or settings that you need to be aware of. See Status bars for solutions.
How do I autostart my favorite apps?
Using the window rules to assign apps to workspace you can setup a session start script to open a bunch of applications on various workspaces. The following method will start these apps silently (i.e. without the flickering from workspace to workspace) and deassign the rule so that subsequent start of this app will not start it on the initially assigned workspace (which could be a drag if e.g. you want kitty to be started on ws 1 while you need kitty to open on any workspace subsequently).
Put the following in your hyprland.conf
: (example)
windowrule=workspace 1 silent,kitty
windowrule=workspace 1 silent,Subl
windowrule=workspace 3 silent,Mailspring
windowrule=workspace 4 silent,firefox
[...]
exec-once=kitty
exec-once=subl
exec-once=mailspring
exec-once=firefox
[...]
exec-once=cleanup_after_start.sh
where cleanup_after_start.sh
script contains:
sleep 10
hyprctl keyword windowrule "workspace unset,kitty"
hyprctl keyword windowrule "workspace unset,Subl"
hyprctl keyword windowrule "workspace unset,Mailspring"
hyprctl keyword windowrule "workspace unset,firefox"
in sleep 10
, the 10 seconds is of course only a suggestion.
How do I move my favorite workspaces to a new monitor when I plug it in?
if you want workspaces to automatically go to a monitor upon connection, use the following:
In hyprland.conf:
exec-once=handle_monitor_connect.sh
where handle_monitor_connect.sh
is: (example)
#!/bin/sh
handle() {
case $1 in monitoradded*)
hyprctl dispatch moveworkspacetomonitor "1 1"
hyprctl dispatch moveworkspacetomonitor "2 1"
hyprctl dispatch moveworkspacetomonitor "4 1"
hyprctl dispatch moveworkspacetomonitor "5 1"
esac
}
socat - UNIX-CONNECT:/tmp/hypr/.socket2.sock | while read -r line; do handle "$line"; done
if you want workspaces 1 2 4 5 to go to monitor 1 when connecting it.
Please note this requires socat
to be installed.
My tablet no worky??
Use Open Tablet Driver to configure your tablet. In the future it will be supported in the config. Until then, OTD is the way to go.
Some of my apps take a really long time to open...?
~/.config/hypr/hyprland.conf
exec-once=dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
Make sure that your portals launch after this gets executed. For some people, they might launch before that has happened.
In such cases, a script like this:
#!/bin/bash
sleep 4
killall xdg-desktop-portal-wlr
killall xdg-desktop-portal
/usr/lib/xdg-desktop-portal-wlr &
sleep 4
/usr/lib/xdg-desktop-portal &
launched with exec-once
should fix all issues. Adjust the sleep durations to taste.
How do I export envvars for Hyprland?
As with any Display Server, Xorg included, you should probably make a script to launch it, for example:
export AMONG_US=1
exec Hyprland
and launch that.
For Display Manager users, you can replace the exec
entry in
the .desktop
file to point to your script. You are recommended
to use absolute paths, such as /home/username/Script
instead of ~/Script
How to disable middle-click paste?
The middle-click paste action pastes from a separate buffer (primary buffer) than what the regular clipboard uses (clipboard buffer). Since the primary buffer is unrelated to the clipboard buffer, it's easy to simply keep the primary buffer empty, allowing the middle-click action to retain the rest of its functionality without having anything to paste. Run the following command (in your config with exec-once
, for example) to achieve this:
wl-paste -p --watch wl-copy -pc
(wl-paste -p --watch
watches for changes to the primary buffer, wl-copy -pc
clears the primary buffer)
Alternatively, you can simply intercept the middle-click action all together, via hyprland binds for example. The drawbacks to this solution are that 1. it disables the rest of the functionality of the middle-click action, such as auto scroll, closing browser tabs, etc., and 2. many applications (such as kitty) manually intercept the middle-click events and bind them to paste from the primary buffer themselves, bypassing the solution altogether. For this solution, add this bind to your config:
bind = , mouse:274, exec, ;
. Note that the exact bindcode may vary, so you may want to check it with wev
first.
How do I make Hyprland draw as little power as possible on my laptop?
I assume you already have damage_tracking
on full. If you don't, change it.
It's heavily advised to use full
regardless of anything.
How do I get information about windows like the class on wayland? xprop no worky.
Hyprctl can list available information about all open windows with the command hyprctl clients
To list only information about a single selected windows, Hyprctl has the command hyprctl activewindow
. This will output information about the currently active window, which is probably your terminal emulator. You can get informationen from other windows by issueing this command in the shell sleep 5 && hyprctl activewindow
, focusing the window you want info about and waiting until the five seconds are over.
Useful Optimizations:
-
decoration:blur_new_optimizations = true
, to use new optimizations for blurring. -
decoration:blur = false
anddecoration:drop_shadow = false
to disable fancy but battery hungry effects. -
misc:vfr = true
, since it'll lower the amount of sent frames when nothing is happening on-screen.
How to fix games with window dancing?
Read this trick.
My apps take a long time to start / can't screenshare
See The XDPH Page.
You most likely have multiple portal impls / an impl is failing to launch.