NixOS Configuration Guide

This NixOS configuration repository uses a modular, hierarchical import structure to manage system and home-manager configurations across multiple environments and desktop setups.

Architecture Overview
Directory Structure
How Import Wranglers Work
Switching Environments
Configuration Layers
Modifying Configurations

Architecture Overview

The configuration follows a layered orchestrator pattern:

flake.nix (entry point)
  ↓
configuration.nix (system orchestrator)
  ├─ hardware-configuration.nix (hardware specifics)
  ├─ modules/nixos/base/ (system-wide config)
  │   └─ default.nix (orchestrator)
  │       ├─ nix.nix
  │       ├─ boot.nix
  │       ├─ networking.nix
  │       ├─ users.nix
  │       ├─ services.nix
  │       ├─ programs.nix
  │       ├─ graphics.nix
  │       └─ packages.nix
  └─ modules/nixos/{i3wm,hyprland}/ (environment-specific)

mun.nix (home-manager orchestrator)
  ├─ modules/home/i3wm/default.nix (orchestrator)
  │   ├─ dunst.nix
  │   ├─ i3.nix
  │   ├─ kitty.nix
  │   ├─ neovim.nix
  │   ├─ nnn.nix
  │   ├─ picom.nix
  │   ├─ polybar.nix
  │   ├─ rofi.nix
  │   ├─ scripts.nix
  │   └─ xdg.nix
  └─ modules/home/hyprland/default.nix (orchestrator)
      └─ chernobyl/default.nix (orchestrator)
          ├─ dunst.nix
          ├─ fastfetch.nix
          ├─ hyprland.nix
          └─ kitty.nix

Directory Structure

.
├── flake.nix                              # Flake inputs/outputs definition
├── flake.lock                             # Lock file for reproducibility
├── configuration.nix                      # Main system config (thin orchestrator)
├── hardware-configuration.nix             # Hardware-specific config (generated)
├── mun.nix                                # Home-manager user config (orchestrator)
├── modules/
│   ├── nixos/
│   │   ├── base/                          # Base system config (split modules)
│   │   │   ├── default.nix                # Orchestrator: imports all base modules
│   │   │   ├── nix.nix                    # Nix settings, flakes, substituters
│   │   │   ├── boot.nix                   # Boot loader, kernel, Plymouth
│   │   │   ├── networking.nix             # Hostname, NetworkManager, Bluetooth
│   │   │   ├── users.nix                  # User definitions
│   │   │   ├── services.nix               # System services (SSH, Pipewire, Printing, Ly)
│   │   │   ├── programs.nix               # System programs (Firefox, Zsh, Steam)
│   │   │   ├── graphics.nix               # GPU drivers, hardware acceleration
│   │   │   └── packages.nix               # System-wide packages
│   │   ├── i3wm/
│   │   │   └── default.nix                # X11, i3 window manager config
│   │   └── hyprland/
│   │       └── default.nix                # Wayland, Hyprland config
│   └── home/
│       ├── i3wm/
│       │   ├── default.nix                # Orchestrator: imports all i3wm home modules
│       │   ├── dunst.nix                  # Notification daemon (i3 config)
│       │   ├── i3.nix                     # i3 window manager config (keybinds, layout)
│       │   ├── kitty.nix                  # Terminal emulator (i3 config)
│       │   ├── neovim.nix                 # Text editor with LazyVim setup
│       │   ├── nnn.nix                    # File browser
│       │   ├── picom.nix                  # X11 compositor
│       │   ├── polybar.nix                # Status bar (i3 specific)
│       │   ├── rofi.nix                   # Application launcher
│       │   ├── scripts.nix                # Custom shell scripts
│       │   └── xdg.nix                    # XDG MIME type defaults
│       └── hyprland/
│           ├── default.nix                # Orchestrator: imports Hyprland rices
│           └── chernobyl/                 # "Chernobyl" Hyprland rice
│               ├── default.nix            # Orchestrator for chernobyl rice
│               ├── dunst.nix              # Notification daemon (Hyprland config)
│               ├── fastfetch.nix          # System info display
│               ├── hyprland.nix           # Hyprland window manager config
│               └── kitty.nix              # Terminal emulator (Hyprland config)

How Import Wranglers Work

An "import wrangler" is a default.nix file that acts as a local aggregator, collecting all related configurations into one place for easy management. This pattern appears at multiple levels:

Level 1: Base System Configuration

File: modules/nixos/base/default.nix

{ ... }:

{
  imports = [
    ./nix.nix
    ./boot.nix
    ./networking.nix
    ./users.nix
    ./services.nix
    ./programs.nix
    ./graphics.nix
    ./packages.nix
  ];

  system.stateVersion = "25.11";
}

Purpose: Groups all foundational system configurations (boot, networking, users, services, packages) into a single import point. When you need to add a base system feature, you either:

Add it to an existing module file
Create a new module (e.g., firewall.nix) and add it to this import list

Benefits:

Single import in configuration.nix: ./modules/nixos/base
All base modules are in one place; easy to see what's included
New base modules are simply added to the imports list

Level 2: Environment-Specific System Configuration

Files: modules/nixos/i3wm/default.nix, modules/nixos/hyprland/default.nix

These are currently thin wrappers but follow the same pattern. To extend them (e.g., add environment-specific services or packages), you would create sub-modules:

# Example expansion of modules/nixos/i3wm/default.nix
{ ... }:

{
  imports = [
    ./xserver.nix        # X11-specific settings
    ./i3.nix            # i3 window manager
    ./keyboard.nix      # Czech keyboard layout
  ];
}

Level 3: Home-Manager Orchestration

File: modules/home/i3wm/default.nix

{ ... }:

{
  imports = [
    ./dunst.nix
    ./i3.nix
    ./kitty.nix
    ./neovim.nix
    ./nnn.nix
    ./picom.nix
    ./polybar.nix
    ./rofi.nix
    ./scripts.nix
    ./xdg.nix
  ];
}

Purpose: All i3wm-specific home-manager modules (dunst, i3 keybinds, polybar, etc.) are collected here. This is imported once in mun.nix, rather than importing 10 separate files.

Benefits:

One line in mun.nix: ./modules/home/i3wm/default.nix
All i3 home configs are clearly grouped
Easy to switch entire environments with a single comment/uncomment

Level 4: Multi-Rice Support (Hyprland)

File: modules/home/hyprland/default.nix

{ ... }:

{
  imports = [
    #./default.nix              # main hyprland rice (future)
    ./chernobyl/default.nix     # chernobyl hyprland rice
  ];
}

File: modules/home/hyprland/chernobyl/default.nix

{ ... }:

{
  imports = [
    ./dunst.nix
    ./fastfetch.nix
    ./hyprland.nix
    ./kitty.nix
  ];
}

Purpose: Supports multiple visual rices/themes for the same window manager. The parent orchestrator selects which rice to use.

Benefits:

Scale to many rices easily (add ./cyberpunk/default.nix, ./nord/default.nix, etc.)
Each rice has its own folder with consistent structure
Switch rices by commenting/uncommenting in the parent orchestrator

Switching Environments

Switch from i3wm to Hyprland

Edit two files:

1. System Configuration (`configuration.nix`)

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

{
  imports = [
    ./hardware-configuration.nix
    ./modules/nixos/base
    
    # === Environment Choice ===
    # Uncomment one of the following to select your environment:
    #./modules/nixos/i3wm      # ← comment this
    ./modules/nixos/hyprland   # ← uncomment this
  ];
}

2. Home-Manager Configuration (`mun.nix`)

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

{
  imports = [
    #./modules/home/i3wm/default.nix      # ← comment this
    ./modules/home/hyprland/default.nix   # ← uncomment this
  ];
  
  # ... rest of mun.nix
}

3. Rebuild

sudo nixos-rebuild switch

Configuration Layers

The configuration is organized in four distinct layers:

1. System-Wide Base (`modules/nixos/base/`)

Applied to all environments.

Includes:

Nix settings (flakes, substituters)
Boot configuration (GRUB, EFI, kernel)
Networking (hostname, NetworkManager, Bluetooth)
Users (mun user definition)
System services (SSH, Pipewire, Printing, Ly display manager)
System programs (Firefox, Zsh, Steam)
Graphics drivers (Intel VAAPI, hardware acceleration)
System packages (Neovim, Git, TeX Live, RetroArch, etc.)

Modify by: Editing existing files in base/ or creating new ones and adding them to base/default.nix.

2. Environment-Specific System (`modules/nixos/{i3wm,hyprland}/`)

Applied to one environment at a time (X11 vs Wayland).

i3wm includes:

X11 enable
i3 window manager
Keyboard layout (Czech)
Display manager session

Hyprland includes:

X11 disable
Hyprland enable
XDG portal for Wayland
Qt6 Wayland support
Keyboard layout (Czech)

Modify by: Editing the respective default.nix or creating sub-modules.

3. Home-Manager User-Wide Config (`mun.nix`)

Configuration applied to user mun only.

Includes:

SSH setup
Shell configuration (Zsh with oh-my-zsh)
Environment variables
Gnome-keyring service
User packages (Rust tools, Discord, utilities)
Environment-specific home-manager orchestrator import

Modify by: Editing mun.nix directly or adding packages to the packages list.

4. Environment-Specific Home-Manager (`modules/home/{i3wm,hyprland}/`)

Applied to one environment at a time.

i3wm includes:

i3 keybindings and layout
Polybar status bar
Dunst notifications
Picom compositor
Rofi launcher
NeoVim with LazyVim
Kitty terminal
Custom scripts
XDG MIME type defaults

Hyprland (chernobyl rice) includes:

Hyprland config
Dunst notifications
Kitty terminal
Fastfetch system info

Modify by: Editing the respective module files or adding new ones to the orchestrator default.nix.

Modifying Configurations

Add a New System Package

File: modules/nixos/base/packages.nix

environment.systemPackages = with pkgs; [
  # ... existing packages ...
  my-new-package  # ← add here
];

Add a New Base System Service

File: modules/nixos/base/services.nix or create modules/nixos/base/firewall.nix

If adding firewall rules, create a new file:

# modules/nixos/base/firewall.nix
{ config, lib, pkgs, ... }:

{
  networking.firewall.allowedTCPPorts = [ 80 443 ];
}

Then add to orchestrator:

# modules/nixos/base/default.nix
{ ... }:

{
  imports = [
    ./nix.nix
    ./boot.nix
    ./networking.nix
    ./users.nix
    ./services.nix
    ./programs.nix
    ./graphics.nix
    ./packages.nix
    ./firewall.nix  # ← add here
  ];

  system.stateVersion = "25.11";
}

Add an i3wm Home-Manager Module

File: modules/home/i3wm/my-new-config.nix

{ config, pkgs, ... }:

{
  # Your home-manager config here
}

Then add to orchestrator:

# modules/home/i3wm/default.nix
{ ... }:

{
  imports = [
    ./dunst.nix
    ./i3.nix
    # ... other modules ...
    ./my-new-config.nix  # ← add here
  ];
}

Add a New Hyprland Rice

Create a new directory:

mkdir modules/home/hyprland/cyberpunk

Add files:

# modules/home/hyprland/cyberpunk/default.nix
{ ... }:

{
  imports = [
    ./dunst.nix
    ./hyprland.nix
    ./kitty.nix
  ];
}

Update parent orchestrator:

# modules/home/hyprland/default.nix
{ ... }:

{
  imports = [
    #./default.nix
    ./chernobyl/default.nix
    #./cyberpunk/default.nix  # ← uncomment to use
  ];
}

Rebuilding Your System

After making changes:

# Switch to new system configuration
sudo nixos-rebuild switch

# Or, test first (doesn't activate)
sudo nixos-rebuild test

# Show what changed
sudo nixos-rebuild dry-run

To edit and rebuild in one step:

# If you have the 'edit' alias from mun.nix
edit
sudo nixos-rebuild switch

Key Principles

One Import Per Layer: Each default.nix orchestrator imports related modules, reducing clutter in parent files.
Separation of Concerns: System config (nixos/) is separate from user config (home/); base is separate from environment-specific.
Easy Environment Switching: Change environments by commenting one line in configuration.nix and mun.nix.
Scalability: Adding new features (base services, home modules, rices) follows a consistent pattern of creating a file + adding it to the orchestrator.
Clarity: Each file has a clear purpose; finding where to modify something is straightforward.

Example Workflow

Goal: Add Firefox configuration to i3wm

Create modules/home/i3wm/firefox.nix:

{ config, pkgs, ... }:

{
  programs.firefox = {
    enable = true;
    profiles.mun = {
      settings = {
        "browser.startup.homepage" = "about:home";
      };
    };
  };
}

Add to orchestrator in modules/home/i3wm/default.nix:

imports = [
  ./dunst.nix
  ./firefox.nix  # ← add here
  ./i3.nix
  # ... rest
];

Rebuild:
```
sudo nixos-rebuild switch
```

Done! Firefox is now configured for the i3wm environment.

Troubleshooting

"Module not found" error

Check that all imports in default.nix files reference correct file paths. Use absolute paths from the module directory:

./nix.nix ✓ (correct)
../base/nix.nix ✓ (correct, relative to parent)
/absolute/path/nix.nix ✗ (avoid; use relative)

Environment not loading after switch

Ensure both configuration.nix and mun.nix have the same environment enabled (not one i3wm and one hyprland).

Syntax errors in .nix files

Use nix flake check to validate:

nix flake check

NixOS Configuration Guide

Table of Contents

Architecture Overview

Directory Structure

How Import Wranglers Work

Level 1: Base System Configuration

Level 2: Environment-Specific System Configuration

Level 3: Home-Manager Orchestration

Level 4: Multi-Rice Support (Hyprland)

Switching Environments

Switch from i3wm to Hyprland

1. System Configuration (`configuration.nix`)

2. Home-Manager Configuration (`mun.nix`)

3. Rebuild

Configuration Layers

1. System-Wide Base (`modules/nixos/base/`)

2. Environment-Specific System (`modules/nixos/{i3wm,hyprland}/`)

3. Home-Manager User-Wide Config (`mun.nix`)

4. Environment-Specific Home-Manager (`modules/home/{i3wm,hyprland}/`)

Modifying Configurations

Add a New System Package

Add a New Base System Service

Add an i3wm Home-Manager Module

Add a New Hyprland Rice

Rebuilding Your System

Key Principles

Example Workflow

Goal: Add Firefox configuration to i3wm

Troubleshooting

"Module not found" error

Environment not loading after switch

Syntax errors in .nix files

References

NixOS Configuration Guide

Table of Contents

Architecture Overview

Directory Structure

How Import Wranglers Work

Level 1: Base System Configuration

Level 2: Environment-Specific System Configuration

Level 3: Home-Manager Orchestration

Level 4: Multi-Rice Support (Hyprland)

Switching Environments

Switch from i3wm to Hyprland

1. System Configuration (configuration.nix)

2. Home-Manager Configuration (mun.nix)

3. Rebuild

Configuration Layers

1. System-Wide Base (modules/nixos/base/)

2. Environment-Specific System (modules/nixos/{i3wm,hyprland}/)

3. Home-Manager User-Wide Config (mun.nix)

4. Environment-Specific Home-Manager (modules/home/{i3wm,hyprland}/)

Modifying Configurations

Add a New System Package

Add a New Base System Service

Add an i3wm Home-Manager Module

Add a New Hyprland Rice

Rebuilding Your System

Key Principles

Example Workflow

Goal: Add Firefox configuration to i3wm

Troubleshooting

"Module not found" error

Environment not loading after switch

Syntax errors in .nix files

References

1. System Configuration (`configuration.nix`)

2. Home-Manager Configuration (`mun.nix`)

1. System-Wide Base (`modules/nixos/base/`)

2. Environment-Specific System (`modules/nixos/{i3wm,hyprland}/`)

3. Home-Manager User-Wide Config (`mun.nix`)

4. Environment-Specific Home-Manager (`modules/home/{i3wm,hyprland}/`)