Faq

Possible causes:

Your themes are not set up properly, making apps crash.

Use something like qt5ct (QT) and lxappearance (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

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.

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.

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 or OBS Studio could be used.

Check Screensharing.

Also install qt6-wayland if you plan to use obs.

See Wallpapers.

Use gamescope, tends to fix any and all issues with wayland/Hyprland.

Not that much heavier than Xorg. If you want maximum performance, consider turning off the blur and animations.

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

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.

Use a wayland-compatible locking utility using WLR protocols, e.g. swaylock.

Use a tool like for example lxappearance to change the GTK cursor.

After that, add exec-once=hyprctl setcursor [THEME] [SIZE] to your config and restart Hyprland.

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 in your wrapper.

Alternatively, change the config files manually 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 lxappearance).

Then, do a gsettings set $gnome-schema cursor-theme 'theme-name' and you’re all good!

If it still doesn’t work…

https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland

Make sure you have a notification daemon running, for example dunst. Autostart it with the exec-once keyword.

Waybar has a set of caveats or settings that you need to be aware of. See Status bars for solutions.

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.

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

function handle {
  if [[ ${1:0:12} == "monitoradded" ]]; then
    hyprctl dispatch moveworkspacetomonitor "1 1"
    hyprctl dispatch moveworkspacetomonitor "2 1"
    hyprctl dispatch moveworkspacetomonitor "4 1"
    hyprctl dispatch moveworkspacetomonitor "5 1"
  fi
}

socat - UNIX-CONNECT:/tmp/hypr/.socket2.sock | while read 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.

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.

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

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

In your config, add this bind: bind = , mouse:274, exec, ;. Note that the exact bindcode may vary, so you may want to check it with wev first.

Note that some software, like kitty, intercepts middle-click events and binds them to paste from primary on their own. Their configurations will need to be changed to account for that.

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.

Useful Optimizations:

• decoration:blur_new_optimizations = true, to use new optimizations for blurring.

• decoration:blur = false and decoration: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.

Read this trick.

See The XDPH Page.

You most likely have multiple portal impls / an impl is failing to launch.