Desktop Environments Guide

This NixOS template supports multiple desktop environments with optimized configurations for different workflows and preferences.

Available Desktop Environments

GNOME Desktop

Modern desktop with excellent Wayland support and polished user experience.

Features:

Configuration:

modules.desktop.gnome = {
  enable = true;
  # No additional configuration needed for basic setup
};

Best for: Users who want a polished, modern desktop experience with minimal configuration.

Hyprland Tiling Window Manager

Modern Wayland compositor with advanced tiling capabilities.

Features:

Basic Configuration:

modules.desktop.hyprland = {
  enable = true;
  waybar.enable = true;          # Status bar
  dunst.enable = true;           # Notifications
};

Niri Scrollable Tiling Window Manager

Unique scrollable tiling compositor with innovative column-based layout.

Features:

Basic Configuration:

modules.desktop.niri = {
  enable = true;
  waybar.enable = true;          # Status bar
  dunst.enable = true;           # Notifications
  scrolling = {
    workspaces = true;           # Enable workspace scrolling
    columns = true;              # Enable column scrolling
  };
};

Advanced Configuration:

modules.desktop.niri = {
  enable = true;

  waybar = {
    enable = true;
    position = "top";
    theme = "catppuccin-mocha";
    modules = {
      workspaces = "niri/workspaces";   # Niri-specific workspace module
      window = "niri/window";           # Niri window titles
      clock = true;
      battery = true;
      network = true;
      pulseaudio = true;
      tray = true;
    };
  };

  dunst = {
    enable = true;
    theme = "catppuccin-mocha";
    position = "top-right";
    transparency = 90;
  };

  applications = {
    terminal = "alacritty";      # Default terminal
    launcher = "fuzzel";         # App launcher (recommended for niri)
    browser = "firefox";         # Default browser
    fileManager = "thunar";      # File manager
  };

  scrolling = {
    workspaces = true;           # Enable workspace scrolling
    columns = true;              # Enable column scrolling
    mouse = {
      workspaceScroll = true;    # Mouse wheel workspace switching
      columnScroll = true;       # Mouse wheel column switching
      scrollCooldown = 150;      # Cooldown between scrolls (ms)
    };
  };

  theme = {
    colorScheme = "dark";        # dark, light, auto
    wallpaper = "/path/to/wallpaper.jpg";
    borders = {
      width = 2;
      radius = 8;
      color = "#cba6f7";         # Catppuccin purple
    };
    gaps = {
      inner = 8;
      outer = 16;
    };
  };

  # Window rules for specific applications
  windowRules = [
    {
      match = { app-id = "firefox"; };
      default-column-width = { proportion = 0.75; };
    }
    {
      match = { app-id = "code"; };
      default-column-width = { proportion = 0.6; };
    }
    {
      match = { app-id = "alacritty"; };
      default-column-width = { proportion = 0.4; };
    }
  ];
};

Best for: Users who want a unique tiling experience with smooth scrolling workflows, especially those with ultrawide monitors.

Hyprland Advanced Configuration

modules.desktop.hyprland = {
  enable = true;

  settings = {
    monitors = [
      "DP-1,1920x1080@60,0x0,1"
      "DP-2,1920x1080@60,1920x0,1"
    ];

    appearance = {
      gaps_in = 8;
      gaps_out = 16;
      border_size = 2;
      rounding = 8;
    };

    animations = {
      enable = true;
      speed = 1.0;
    };
  };

  waybar = {
    enable = true;
    position = "top";
    theme = "colorful";
    modules = {
      workspaces = true;
      window = true;
      clock = true;
      battery = true;
      network = true;
      pulseaudio = true;
      tray = true;
    };
  };

  applications = {
    terminal = "alacritty";      # Default terminal
    launcher = "wofi";           # App launcher
    fileManager = "thunar";      # File manager
    browser = "firefox";         # Web browser
  };

  theme = {
    colorScheme = "dark";        # dark, light, auto
    wallpaper = "/path/to/wallpaper.jpg";
    cursor = {
      theme = "Adwaita";
      size = 24;
    };
  };
};

Best for: Advanced users who prefer keyboard-driven workflows and tiling window management.

Niri Best Use Cases

Best for: Users who want a unique tiling experience with smooth scrolling workflows, especially those with ultrawide monitors or multiple displays.

Desktop Environment Comparison

All three are Wayland-native; the template no longer ships an X11 session.

Feature GNOME Hyprland Niri
Learning Curve Easy Advanced Moderate
Customization Limited Complete High
Resource Usage Moderate Light Very Light
Touch Support Excellent None None
Gaming Good Good Good
Configured via dconf Home Manager Home Manager
Unique Feature Polished UX Animations Scrollable Tiling

Where the configuration lives

GNOME is configured through the NixOS module (modules.desktop.gnome) and dconf. Hyprland and niri are configured through Home Manager, so a user can override a single binding without replacing the whole file:

# Hyprland — home/profiles/hyprland.nix
wayland.windowManager.hyprland.settings = {
  "$mod" = "SUPER";
  bind = [ "$mod, Q, exec, alacritty" ];
};

# niri — home/profiles/niri.nix, via the niri-flake module
programs.niri.settings.binds = with config.lib.niri.actions; {
  "Mod+T".action = spawn "alacritty";
};

Earlier versions wrote /etc/hypr/hyprland.conf and /etc/niri/config.kdl from inline Nix strings. Those were system-wide, so nothing could be overridden per user, and a config language embedded in a Nix string gets no LSP and no formatter.

niri has no module in nixpkgs or home-manager, which is why niri-flake is an input.

Configuration Guide

Choosing a Desktop Environment

Edit your host configuration file (e.g., hosts/your-hostname/configuration.nix):

modules.desktop = {
  # Choose ONE desktop environment
  gnome.enable = true;
  # hyprland.enable = true;
  # niri.enable = true;

  # Common desktop modules
  audio.enable = true;
  fonts.enable = true;
  graphics.enable = true;
};

Home Manager Integration

Each desktop environment includes Home Manager configurations for user-specific settings.

GNOME Home Configuration:

# Import GNOME profile
imports = [ ../../../home/profiles/gnome.nix ];

Hyprland Home Configuration:

# Import Hyprland profile
imports = [ ../../../home/profiles/hyprland.nix ];

Niri Home Configuration:

# Import Niri profile
imports = [ ../../../home/profiles/niri.nix ];

Multiple Users

Different users can have different desktop preferences:

# System configuration - enable multiple environments
modules.desktop = {
  gnome.enable = true;
  hyprland.enable = true;  # Both available at login
  niri.enable = true;      # Three desktop environments
};

# User 1 - GNOME preference
home-manager.users.alice = {
  imports = [ ./home/profiles/gnome.nix ];
};

# User 2 - Hyprland preference
home-manager.users.bob = {
  imports = [ ./home/profiles/hyprland.nix ];
};

# User 3 - Niri preference
home-manager.users.charlie = {
  imports = [ ./home/profiles/niri.nix ];
};

Desktop-Specific Features

GNOME Features

Extensions:

Applications:

Keyboard Shortcuts:

Hyprland Features

Tiling Management:

Status Bar (Waybar):

Applications:

Key Bindings:

Niri Features

Scrollable Tiling:

Column Management:

Status Bar (Waybar with Niri modules):

Applications:

Unique Key Bindings:

Window Rules:

Troubleshooting

Display Issues

GNOME:

Hyprland:

Niri:

Performance Optimization

GNOME:

Hyprland:

Niri:

Application Integration

Theme Consistency:

Font Rendering:

Managing Desktop Environments

Commands

# List available desktop environments
just list-desktops

# Test desktop configuration
just test-desktop gnome
just test-desktop niri

# Build specific configuration
just build example-desktop

# Switch desktop environment (requires configuration change)
just switch

# Niri-specific commands
just test-niri           # Test Niri configuration
just niri-reload         # Reload Niri config (if running)
just niri-keys           # Show keybindings reference
just niri-debug          # Toggle debug tinting
just niri-config-info    # Show config paths and commands

Switching Between Desktops

To switch desktop environments:

  1. Edit your host configuration
  2. Disable current desktop (enable = false)
  3. Enable new desktop (enable = true)
  4. Rebuild system (just switch)
  5. Reboot for clean session

Concurrent Desktop Support

You can enable multiple desktop environments simultaneously:

modules.desktop = {
  gnome.enable = true;
  hyprland.enable = true;
  niri.enable = true;
};

Users can choose at the login screen, but this increases system resource usage.

Best Practices

Performance

Security

Backup

Development

Getting Help

  1. Check desktop-specific logs:
    • GNOME: journalctl --user -u gnome-session
    • Hyprland: Check Hyprland logs in terminal
  2. Verify configuration:
    • nix flake check - Validate flake
    • just test-desktop [name] - Test specific desktop
  3. Community resources:
    • NixOS Discourse for NixOS-specific issues
    • Desktop-specific documentation and forums
    • Home Manager documentation for user configs