Notes on setting up Hyprland

hyprland screenshot

I tried out the Hyprland tiling window manager today, and wrote up some notes that might make a useful cheatsheet for new users.

Configuration, as it turns out, can get pretty involved. These notes are just intended to give a lay of the land, at times from the point of view of someone who wants to get it to work on Debian.

Using Hyprland

Unlike Gnome or KDE, Hyprland is extremely minimal, and a lot of features provided by desktop environments you will have to add piecemeal.

On first use:

<meta>-q to open up a terminal. kitty must be installed, or after having Hyprland write a basic config on first launch, you can change it to a terminal you have. I use rio and it works great. 🦀

You'll probably use <meta>-m to exit a number of times while you're still getting a working config set up.

Open up ~/.config/hypr/hyprland.conf in an editor. You can find out the default keybinds by reading the config, but to get started:

  • <meta>-{1, 2, 3, 4...} to switch to a workspace
  • <shift><meta>-{1, 2, 3, 4...} to move the current window to a workspace
  • <meta>-v to untile or re-tile a window
  • <meta>-t to toggle horizontal and vertical split
  • <meta>-p to toggle "psuedo" for a tile: a window can be resized to be smaller within its tile
  • <meta> and click and drag to move a window
  • <meta> and right-click and drag to resize
  • <meta>-c close window -- think like <Ctrl>-C
  • <meta>-s toggles a special workspace that you can stash things in, on top of the other workspaces. <shift><meta>-s to move a window into it.

I changed the movefocus binds to be like vim:

bind = $mainMod, h, movefocus, l
bind = $mainMod, l, movefocus, r
bind = $mainMod, k, movefocus, u
bind = $mainMod, j, movefocus, d

I have have trouble getting a right-click-and-drag with my trackpad, so in the general section I set resize_on_border to true.

I prefer my Caps Lock to be an Esc key, which can be achieved by setting kb_options = caps:swapescape in the input section.

Launcher

In order to start apps outside of a terminal -- without using a terminal -- you'll need a launcher. wofi is standard and is configured by default, but since it isn't included you'll need to install it separately.

Once you do you can press <meta>-r to run software.

waybar

waybar screenshot

waybar is a statusbar that can show you what workspace is selected, net stats, battery, etc.

It's configured by two files, ~/.config/waybar/config.jsonc and ~/.config/waybar/style.css.

Unlike Hyprland there is no automatic reload. killall -USR2 waybar will force one, but watch out: old CSS is not cleared.

The basic config assumes you have a Font Awesome font installed. I did, but only most of the icons showed up. I ended up using a Nerd Font font I already had installed, and overrode the config with NF icons where applicable.

When working with most examples for waybar, you will want to change the #workspaces button.focused selector (which is what sway uses) to #workspaces button.active.

exec-once

You can specify multiple lines of exec-once. I ended up at

exec-once = sleep 5; 1password --silent
exec-once = sleep 5; nm-applet  # (network manager applet)
exec-once = sleep 5; blueman-applet  # (bluetooth)
exec-once = waybar

I found that adding a sleep 5; before some commands fixes an issue where some tray icons don't appear, likely because they attempt to use the tray before it is ready.

Lock screen

hyprlock wasn't available on Debian. I found swaylock, which does the job, but you probably want hyprlock if it's available.

$lockScreen = swaylock
bind = $mainMod, L, exec, $lockScreen

xdg-desktop-portal-hyprland

You will need to install this package if you want to do screen sharing. It should be started automatically when it is needed.

screenshots

Use hyprshot or grim.

Use Wayland everywhere

Using Wayland in as many places as you can will fix issues on HiDPI screens where apps using xwayland appear pixelated.

Environment variables to do this can be set in hyprland.conf.

env = GDK_BACKEND,wayland,x11,*
env = QT_QPA_PLATFORM,wayland;xcb
env = SDL_VIDEODRIVER,wayland
env = CLUTTER_BACKEND,wayland
env = ELECTRON_OZONE_PLATFORM_HINT,auto

Getting 1password to work with Wayland

1password refuses to open windows when forced into using Wayland with the environment above.

To fix it, do this:

  1. Start 1password without the ELECTRON_OZONE_PLATFORM_HINT=auto environment variable.
  2. Go to Settings
  3. Click Advanced
  4. Turn on "Use Hardware Acceleration"
  5. Close 1password
  6. Restart with the ELECTRON_OZONE_PLATFORM_HINT=auto environment variable.