tonybtw.com

#+TITLE: Hyprland on NixOS (w/ UWSM)

#+AUTHOR: Tony, btw

#+date: 2025-10-08

#+HUGO_TITLE: Hyprland on NixOS (w/ UWSM)

#+HUGO_FRONT_MATTER_FORMAT: yaml

#+HUGO_CUSTOM_FRONT_MATTER: :image "/img/nixos-hyprland.png" :showTableOfContents true

#+HUGO_BASE_DIR: ~/repos/tonybtw.com

#+HUGO_SECTION: tutorial/nixos-hyprland

#+EXPORT_FILE_NAME: index

#+OPTIONS: toc:nil broken-links:mark

#+HUGO_AUTO_SET_HEADLINE_SECTION: nil

#+DESCRIPTION: This is a quick and painless tutorial on how to setup Hyprland on NixOS using flakes + home manager, and optionally using UWSM (the Universal Wayland Session Manager)

* Intro

It's the year 20xx. Everyone's prebuilt PC at best buy comes with Linux and hyprland installed by default. The apple stores have Macbooks with a new propietary version of hyprland called iLand. Your grandson asks you, "My laptop broke, but I don't know how to re-install my operating system. Can you help me??"

What's up guys, my name is Tony, and today, I'm going to give you a quick and painless guide on setting up Hyprland on NixOS optionally with UWSM.

Hyprland is a wayland compositor that really feels like the King of beginner friendly compositors. It just works out of the box, with clean and aesthetically pleasing animations, and its getting more and more people into wayland, and linux in general. If you are converting over from a Desktop Environment such as Gnome, or Kde plasma, and you want to start with a wayland compositor, Hyprland is a great entry level choice.

Setting it up with NixOS is quite easy, so let's jump straight into the installation process.

* Installation

We're jumping straight into the minimal iso, and we'll speed run this since you've probably seen it 3 times by now, but a written guide will be provided below the subscribe button.

First thing we need to do is run lsblk to know what our disk is named. We see its vda, so lets run

#+begin_src sh

cfdisk /dev/vda

#+end_src

And let's setup 2 partitions. First one will be 1gb, and lets change the type to EFI Filesystem, which is going to be our 1 gigabyte boot partition.

Secondly, we'll just hit enter twice to use the remaining space for our root file system. Let's write, type yes, and quit here.

Now lets make the filesystems.

#+begin_src sh

mkfs.ext4 -L nixos /dev/vda2

mkfs.fat -F 32 -n BOOT /dev/vda1

#+end_src

And lets mount these:

#+begin_src sh

mount /dev/vda2 /mnt

mount --mkdir /dev/vda1 /mnt/boot

#+end_src

And we can type lsblk to confirm here:

#+begin_src sh

[root@nixos:~]# lsblk

NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS

loop0    7:0    0  1.5G  1 loop /nix/.ro-store

sr0     11:0    1  1.6G  0 rom  /iso

vda    253:0    0   50G  0 disk

├─vda1 253:1    0    1G  0 part /mnt/boot

└─vda2 253:3    0   49G  0 part /mnt

#+end_src

And we're already ready to generate the nixos configuration file.

** Initial NixOS Config

[[https://nixos.org/manual/nixos/stable/index.html#sec-installation-manual][Official NixOS Installation Handbook]]

Alright, we're ready to generate the config file, so let's do so with the following command:

This part is going to be a lot of configuration and text editing, so if you want everything I've put into these files, just follow along this written article.

#+begin_src

nixos-generate-config --root /mnt

cd /mnt/etc/nixos/

#+end_src

Let's create flake.nix, and home.nix

(This is my minimal vimrc that I use even on install ISOs)

#+begin_src vim

filetype plugin indent on

set expandtab

set shiftwidth=4

set softtabstop=4

set tabstop=4

set number

set relativenumber

set smartindent

set showmatch

set backspace=indent,eol,start

syntax on

#+end_src

*** flake.nix

vim flake.nix

Jumping into our flake.nix, this is where we define where our packages come from, so both configuration.nix and home.nix can inherit them through the flake and use them consistently.

Couple of things worth noting here:

1. nixpkgs is shorthand for github:NixOS/nixpkgs/nixos-unstable

2. inputs.nixpkgs.follows = "nixpkgs": This prevents home-manager from pulling its own version of nixpkgs, keeping everything consistent and avoiding mismatched package sets.

3. This modules section tells our flake to build the system using configuration.nix, and to configure Home Manager for the tony user using home.nix, with some options set inline.

4. We include home-manager as a NixOS module here because we want Home Manager to be managed by the flake itself — meaning we don’t need to bootstrap it separately, and we don’t need to run home-manager switch. Instead, everything gets applied in one go with nixos-rebuild switch.

vim flake.nix

#+begin_src nix

{

  description = "Hyprland on Nixos";

  inputs = {

    nixpkgs.url = "nixpkgs/nixos-unstable";

    home-manager = {

      url = "github:nix-community/home-manager";

      inputs.nixpkgs.follows = "nixpkgs";

    };

  };

  outputs = { self, nixpkgs, home-manager, ... }: {

    nixosConfigurations.nixos-btw = nixpkgs.lib.nixosSystem {

      system = "x86_64-linux";

      modules = [

        ./configuration.nix

        home-manager.nixosModules.home-manager

        {

          home-manager = {

            useGlobalPkgs = true;

            useUserPackages = true;

            users.tony = import ./home.nix;

            backupFileExtension = "backup";

          };

        }

      ];

    };

  };

}

#+end_src

We're ready to move onto our configuration.nix file.

*** configuration.nix

One of the beautiful things about NixOS is that your system is defined in various config files. You can think of it almost like of how your window manager is defined with config files, and you can port your window manager dotfiles to another distro, or another computer, and use the same keybinds/options on both machines. Well nixos has a 'config file' that lives above those window manager dotfiles from a heirerarchical perspective.

Alright, so I'm going to start off by deleting a bunch of comments.

I'll change the hostname here to `nixos-btw`, because I'm using NixOS, by the way.

We'll remove the wpa supplicant option and just uncomment the NetworkManager block here. If you are using wifi, keep the wpa supplicant option, and remove the NetworkManager block instead.

For my situation, I am going to chnage the timezone to America/Los Angeles.

We can delete all these proxy settings comments.

#+begin_src nix

{ config, lib, pkgs, ... }:

{

  imports =

    [

      ./hardware-configuration.nix

    ];

  boot.loader.systemd-boot.enable = true;

  boot.loader.efi.canTouchEfiVariables = true;

  services.getty.autologinUser = "tony";

  networking.hostName = "nixos";

  networking.networkmanager.enable = true;

  time.timeZone = "America/Los_Angeles";

  programs.hyprland = {

    enable = true;

    withUWSM = true;

    xwayland.enable = true;

  };

  users.users.tony = {

    isNormalUser = true;

    extraGroups = [ "wheel" ];

    packages = with pkgs; [

      tree

    ];

  };

  programs.firefox.enable = true;

  environment.systemPackages = with pkgs; [

    vim

    wget

    foot

    waybar

    kitty

  ];

  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  system.stateVersion = "25.05";

}

#+end_src

And we can use the getty auto login service above. Feel free to skip UWSM if you are not interested in it, as it is more or less deprecated.

Alright we're ready to move on to our home.nix.

*** home.nix

Let's set up our home.nix. we'll heavily modify this after installing nixos and logging in for the first time.

Just going to specify the home directory, enable git, and for a sanity check, let's setup a bash alias so we can confirm everything worked when we initially log in.

vim home.nix

#+begin_src nix

{ config, pkgs, ... }:

{

  home.username = "tony";

  home.homeDirectory = "/home/tony";

  home.stateVersion = "25.05";

  programs.git.enable = true;

  programs.bash = {

    enable = true;

    shellAliases = {

      btw = "echo i use nixos, btw";

    };

    profileExtra = ''

      if [ -z "$WAYLAND_DISPLAY" ] && [ "$XDG_VTNR" = 1 ]; then

        exec uwsm start -S hyprland-uwsm.desktop

      fi

    '';

  };

}

#+end_src

** Install:

Alright we're finally ready to install this. We can do that with this command here, to specify the location of the flake.

#+begin_src sh

nixos-install --flake /mnt/etc/nixos#nixos-btw

## type your password

nixos-enter --root /mnt -c 'passwd tony'

reboot

#+end_src

Make sure to create this password otherwise you wont be able to log in

Let's boot into our system!

* Create config file

And we see we are instantly booted into hyprland. Awesome. Let's do a little tinkering here so that our monitor is actually the correct resolution. So we see its super Q to open a terminal, and lets vim the config file. We'll clean this up later, but for now, lets just change this one line here:

To 1920x1080. For me, that should do it.

Alright, I'm going to clone a couple of my dotfiles for my terminal, my hyprland and my waybar configurations. This video is more of a how to install hyprland on nixos video, and I'll show a really cool nix feature after.

#+begin_src sh

mkdir ~/nixos-dotfiles/config

cd ~/nixos-dotfiles/config

git clone https://github.com/tonybanters/hypr

git clone https://github.com/tonybanters/waybay

git clone https://github.com/tonybanters/foot

#+end_src

So in home.nix lets specify that our configs are going to come from config like so:

#+begin_src nix

home.file.".config/hypr".source = ./config/hypr;

home.file.".config/waybar".source = ./config/waybar;

home.file.".config/foot".source = ./config/foot;

#+end_src

And we can rebuild like so:

#+begin_src

sudo nixos-rebuild swith --flake ~/nixos-dotifles#hyprland-btw

#+end_src

* Nix Search TV

So we messed around with nix shells already, lets actually show something that I use on a daily basis, called nix-search-tv. This guide was written up by my friend Emzy, and we can use it to install a great tool that helps us search for nix packages, and use commands to just jump right into a nix shell.

So let's add this to our home manager packages list:

#+begin_src nix

#home.nix

home.packages = with pkgs; [

  (pkgs.writeShellApplication {

    name = "ns";

    runtimeInputs = with pkgs; [

      fzf

      nix-search-tv

    ];

    text = builtins.readFile "${pkgs.nix-search-tv.src}/nixpkgs.sh";

  })

];

#+end_src

Now we can rebuild/switch again, and run ns to demo this. Incredible

* Outro

Alright, thats gonna be it for todays video. If you have any questions or recommendations on any other linux related content, as usual just drop a comment.

It wouldn't be a proper video without an obligatory neofetch.