Hyprland
What Hyprland actually is
When your computer finishes booting, something needs to take control in order to turn the system into a usable desktop. It opens windows on the screen, responds to your keyboard and mouse, and decides where everything is supposed to go. That program is called a compositor.
GNOME and KDE Plasma both have a compositor built into them as part of the larger desktop environment, but Hyprland is a compositor that stands on its own, without a full desktop environment built around it. This way you get exactly what you configure and, mostly, nothing else.
Hyprland runs on Wayland, the modern display protocol used by many GNU/Linux desktop systems. An older system, X11, has been around since the 1980s. Wayland was designed as a newer and simpler approach, where the compositor has much more control over the graphical session. Hyprland is Wayland-only.
You've probably heard me talk about tiling. This means that windows are placed automatically into a layout rather than simply piling on top of one another. Open a second window and the space is divided. Open a third and the layout changes again. You can still pull a window out of the tiling layout and use it as a normal floating window.
Free software and Hyprland
Hyprland is free software. Its source code is available publicly and the project is distributed under the BSD 3-Clause License, which allows users to use, study, modify, and redistribute it under the terms of the license.
Hyprland is not part of the GNU Project, and I am not going to pretend that it is. GNU/Linux is made from many different projects working together. The GNU Project provides a huge amount of software used on GNU/Linux systems, while the Linux kernel provides the kernel itself. Hyprland is another independent project that can be used as part of that environment.
This is one of the reasons I prefer the term GNU/Linux for the complete operating system. Linux, strictly speaking, is the kernel. A GNU/Linux system can contain the Linux kernel, GNU software such as Bash and Coreutils, libraries, a graphical stack, Hyprland, applications, and hundreds of other pieces.
The GNU Project itself was started by Richard Stallman in 1983 with the goal of creating a complete operating system made entirely from free software. The important part of "free" here is freedom, not price. The idea is that users should have the freedom to run software, study how it works, modify it, and share it with others.
Installing everything
Hyprland changes fairly quickly, so old installation guides have a habit of becoming wrong. For that reason, the safest thing to do is use packages supplied by your distribution whenever possible.
The exact command depends on your GNU/Linux distribution. I am only giving a few examples here rather than pretending one command works everywhere. Always check your distribution's current package information first.
Install Hyprland from the official repositories:
sudo pacman -S hyprland
Enable Hyprland in configuration.nix:
programs.hyprland.enable = true;
Install the packaged version:
sudo zypper in hyprland
Availability depends on the Debian release and enabled repositories. Check the current Debian package information rather than using an old command from a different release.
Once Hyprland is installed, log out and choose Hyprland from your display manager. On systems where the session is available from a TTY, you can also start it with:
start-hyprland
Do not run Hyprland itself with sudo.
It is a graphical user session, not an administrative command.
What each piece does
You may have noticed that Hyprland itself is surprisingly small. That is because you are expected to choose the rest of the environment yourself. Don't worry, they are all just separate programs doing separate jobs.
waybar is the status bar. It can show the time, active workspace, battery, volume, network information, and anything else you decide to configure. Without it, you may simply have nothing at the top of the screen.
wofi is an application launcher. A keyboard shortcut opens a small search box where you type a program's name and press Enter. There are plenty of alternatives, so you are not married to Wofi.
hyprpaper handles wallpapers. Hyprland does not need to contain a complete wallpaper system itself, so a separate program can take care of the background.
dunst handles notifications. When another program wants to display a notification, dunst decides how and where that notification appears.
kitty is a terminal emulator. It works well on Wayland, but again, you can replace it with another terminal whenever you like.
grim and slurp can be used together for screenshots. Slurp lets you select a region of the screen and grim captures it.
PipeWire and WirePlumber handle modern GNU/Linux audio. They route sound between applications and hardware such as speakers, headphones, microphones, and USB audio devices.
The SUPER key
Almost everything you do in Hyprland starts by holding one key. It may appear like the Windows logo key, the Command key, or something else depending on your keyboard. In the Hyprland configuration, this key is called SUPER.
Think of it like a special "desktop control" key. When you hold it and press another key, something happens. You can open a terminal, close a window, switch workspaces, move focus, launch programs, and much more. You do not need a taskbar or right-click menu for all of this.
One common shortcut is:
The Q does not stand for anything particularly clever. It was simply chosen because it sits in a convenient place on the keyboard. For something you use constantly, that matters more than having a perfect mnemonic.
If the terminal opened, Hyprland is running correctly. Every other shortcut works in much the same way: hold SUPER, press something else.
Opening and closing windows
These are the controls you will use every single day. Your configuration may differ, but these are common examples:
- Open a terminal SUPER + Q
- Close the focused window SUPER + C
- Move focus left / right / up / down SUPER + Arrows
- Open the application launcher SUPER + D
- Toggle floating mode SUPER + V
- Toggle fullscreen SUPER + F
C to close is easy enough to remember. F for fullscreen is even easier. V to float is the odd one out, so imagine a UFO lifting a window off the tiled layout with a tractor beam.
Workspaces
A workspace is a separate collection of windows. When you switch to another workspace, the programs on the first one are still running; you simply cannot see them at the moment. Switch back and they are exactly where you left them.
A simple way to stay organized is to keep your terminal on workspace 1, your browser on workspace 2, your editor on workspace 3, and your music player somewhere else. You can jump between them without stacking a dozen windows on top of each other.
- Switch to workspace N SUPER + N
- Move the focused window to workspace N SUPER + SHIFT + N
Think of a workspace as another desk. You can walk away from one desk and sit at another without throwing everything on the first desk into the garbage. SUPER+N takes you to desk N. SUPER+SHIFT+N takes the window with you.
Try this: open a terminal on workspace 1. Press SUPER+2 to jump to workspace 2. Open another terminal there. Then press SUPER+1 to return. Your first terminal is exactly where you left it.
The configuration file
This is where Hyprland gets interesting. Instead of digging through a giant graphical settings application, much of the compositor can be configured through text.
Current versions of Hyprland use Lua for their configuration. The main configuration file is normally:
~/.config/hypr/hyprland.lua
Older versions used a file called hyprland.conf
with Hyprland's older configuration language. If you find a guide
online using that format, check how old it is before assuming your
installation uses the same system.
One of the nice things about configuration files is that you can open them with a normal text editor and actually see what your desktop is being told to do. For example:
nano ~/.config/hypr/hyprland.lua
After making a change, you can ask Hyprland to reload its configuration:
hyprctl reload
The other programs around Hyprland have their own configuration files as well. That means you can slowly build an environment piece by piece instead of trying to configure everything at once.
- Hyprland ~/.config/hypr/
- Waybar ~/.config/waybar/
- Wofi ~/.config/wofi/
- Dunst ~/.config/dunst/
- Kitty ~/.config/kitty/
Your first edit: gaps between windows
The most immediately visible thing you can change is the spacing between windows. By default there may be little or no gap, so tiled windows can sit almost flush against each other and the edge of the screen. Adding some space makes the layout much easier to read.
The settings you are looking for are:
gaps_in = 8 gaps_out = 14 border_size = 2
gaps_in is the space between two tiled windows. gaps_out is the space between the layout and the edge of the screen. border_size controls the thickness of the window border.
The exact Lua structure around these settings depends on the rest of your configuration. Do not delete the whole file just to paste these three lines in. Add them where the current documentation says they belong.
Think of all your tiled windows as one big block. In means the empty space inside that block. Out means the empty space between that block and the screen itself.
Autostarting programs
When you first log into Hyprland, you may get a very bare desktop. No bar. No wallpaper. No notifications. Just you and your windows.
That is intentional. Those things come from separate programs, and you decide which ones you want. Once you know what you want running automatically, you can add them to your session startup configuration.
Older Hyprland configurations commonly used lines like these:
exec-once = waybar exec-once = hyprpaper exec-once = dunst
The important idea is the "once". You want these programs to start when your session begins, not every time you reload your configuration. The exact Lua syntax in current versions should be taken from the current Hyprland documentation.
You can do the same thing with a clipboard manager, a polkit authentication agent, an idle daemon, or anything else you want available whenever your desktop starts.
Think of your startup programs as the people setting up a shop before you open for the day. The lights come on, the counter is prepared, the music starts. Once the shop is open, you do not need to hire the same people again every five minutes.
Setting a wallpaper
Hyprland does not have to handle wallpapers itself. That job can be given to a separate program such as hyprpaper.
Save an image somewhere such as:
~/Pictures/wall.jpg
Then configure your wallpaper program according to the version you have installed. Wallpaper software changes independently from Hyprland itself, so an old configuration example may no longer work exactly as written.
Customizing the whole desktop
The Linux community has a tradition called "ricing", which means customizing every visible part of the desktop until it looks exactly the way you want. Custom bars, matching color schemes, rounded corners, blur effects, carefully tuned spacing. The word comes from car culture, where it described adding cosmetic modifications for style.
You do not have to do any of this. A default Hyprland setup works perfectly well as a daily driver. But if you want a specific look, one common approach is to find a "dotfiles" repository: someone else's entire configuration published publicly. You read through it, take the parts you like, and add them to your own config.
github.com/topics/hyprland-dotfiles — Every public GitHub repository tagged with this topic. A useful place to see how other people build their desktops. Read the configuration before copying anything.
reddit.com/r/hyprland — People regularly post screenshots with links to their dotfiles. It is more focused than a general Linux desktop community.
HyDE — github.com/prasanthrangan/hyprdots — An automated setup with multiple bundled themes. Useful if you want to see what a complete pre-built desktop looks like, but read the scripts before running them.
ML4W Dotfiles — github.com/mylinuxforwork/dotfiles — Comes with videos explaining how the setup works. Useful for learning rather than simply copying a finished configuration.
~/.config/hypr/ with someone else's dotfiles without
reading what is in there first. Copy sections into your existing
configuration one piece at a time so you know what each change does.
Color palettes
The fastest way to make a desktop look intentional is to pick one color palette and apply it everywhere: your terminal, your bar, your window borders, your notifications. When those colors match, the setup looks finished without much other effort.
A few palettes are especially popular because they have ports for lots of different programs:
Catppuccin — github.com/catppuccin/hyprland — Four variants ranging from light to very dark. There are ports for Hyprland, Waybar, Kitty, Dunst, and many other programs.
Rose Pine — rosepinetheme.com — Muted warm tones, dusty purples, and rose on dark backgrounds. Subtle but distinctive.
Tokyo Night — github.com/folke/tokyonight.nvim — Deep navy with blue and purple accents. There are many Hyprland configurations based on it.
Gruvbox — github.com/morhetz/gruvbox — Warm amber and green on dark brown. Very widely ported and particularly pleasant for long terminal sessions.
Apply a palette to your terminal first since it is the fastest place to see results. Then change Waybar's colors and finally the Hyprland border colors. Those three matching is often enough to make the whole desktop feel like one coherent design.
Finished
That's all folks!
You have installed Hyprland, understood what each part does, learned to move around, worked with workspaces, looked at the configuration, set up startup programs, set a wallpaper, and seen how people customize their desktops. You've got a working desktop now.
The full reference for current configuration options is at wiki.hypr.land. It covers monitors, animations, window rules, workspace behavior, plugins, and much more. Hyprland changes fairly quickly, so the current documentation is much more useful than a random guide from three years ago.
The configuration file is all yours now, like keys to a car. You can change whatever bothers you. You can make the steering feel different, repaint it, rearrange the controls, or completely change what the thing looks like. The same basic idea applies here, except you do not have to worry about putting the keys in the ignition.
If something breaks, stop and read the error message before changing anything else. Then undo the last change, fix it, and try again. Most problems become much less frightening once you understand what you actually changed.
The nice thing about Hyprland is that you can change almost anything. Don't like the bar? Replace it. Don't like the launcher? Replace it. Want different keybindings? Change them. The whole point is that you decide how the desktop works. You only need time and patience.