Skip to content

Installation

Jump to bottom
NullString1 edited this page Jan 13, 2026 · 2 revisions

Installation Guide

Complete guide to installing NullOS on your system.

Prerequisites

Before installing NullOS, ensure you have:

  • ✅ A working NixOS installation
  • ✅ Git installed (nix-shell -p git)
  • ✅ Nix flakes enabled
  • ✅ Basic familiarity with NixOS concepts

Step 1: Enable Flakes

If you haven't already enabled flakes, add this to /etc/nixos/configuration.nix:

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

Then rebuild:

sudo nixos-rebuild switch

Step 2: Clone the Repository

Clone NullOS to your home directory or preferred location:

git clone https://github.com/yourusername/NullOS.git ~/NullOS
cd ~/NullOS

Step 3: Configure Variables

NullOS uses a variables.nix file for per-machine configuration.

Create Your Variables File

cp variables.nix.example variables.nix

Edit Variables

Open variables.nix and customize:

{ nixpkgs, ... }:
let
  pkgs = import nixpkgs { system = "x86_64-linux"; };
in
{
  # User Configuration
  username = "youruser";
  hostname = "yourhostname";
  gitUsername = "Your Name";
  gitEmail = "your@email.com";

  # System
  system = "x86_64-linux";
  timeZone = "Europe/London";
  locale = "en_GB.UTF-8";
  keyboardLayout = "gb";
  consoleKeyMap = "uk";

  # Applications
  terminal = "ghostty";
  browser = pkgs.brave;  # or pkgs.firefox, pkgs.chromium

  # NVIDIA (for hybrid graphics laptops)
  useNvidiaPrime = false;  # Set to true if you have NVIDIA + Intel
  intelBusId = "PCI:0:2:0";
  nvidiaBusId = "PCI:2:0:0";

  # Theming
  stylixImage = wallpapers/screen.jpg;
  waybarConfig = home/waybar/default.nix;
  animationSet = home/hyprland/animations-end4.nix;

  # Backup (optional)
  resticRepository = "sftp:user@host:/backup/path";

  # Monitor Configuration
  extraMonitorSettings = "
    monitor = eDP-1, 1920x1080@60,auto,1
    ";

  # Printing
  printEnable = true;
  printDrivers = [ ];

  # Hardware
  add_rtl8852cu = false;
}

See Variables Reference for detailed explanations of all options.

Step 4: Generate Hardware Configuration

Generate hardware configuration for your machine:

sudo nixos-generate-config --show-hardware-config > /tmp/hardware.nix

Step 5: Create Hardware Module

Create a hardware configuration file for your new machine. You can start by copying an existing configuration as a template:

cp modules/system/hardware_nslapt.nix modules/system/hardware_yourhostname.nix

Then, open modules/system/hardware_yourhostname.nix and update the hardware-specific sections using the content from /tmp/hardware.nix generated in the previous step.

Key sections to update:

  • boot.initrd.availableKernelModules
  • boot.kernelModules
  • fileSystems (ensure UUIDs match your system)
  • swapDevices
  • networking.hostName (set to "yourhostname")

Step 6: Update Flake Configuration

Edit flake.nix to add your machine (or modify an existing configuration):

nixosConfigurations = {
  yourhostname = nixpkgs.lib.nixosSystem {
    inherit system;
    specialArgs = {
      inherit vars;
      inherit inputs;
      inherit home-manager;
    };
    pkgs = import nixpkgs {
      inherit system;
      overlays = overlays;
      config = {
        allowUnfree = true;
        android_sdk.accept_license = true;
      };
    };
    modules = [
      inputs.home-manager.nixosModules.home-manager
      {
        home-manager.useUserPackages = true;
        home-manager.backupFileExtension = "backup";
        home-manager.extraSpecialArgs = {
          inherit vars;
          inherit inputs;
          username = vars.username;
        };
        home-manager.users.${username} = {
          imports = [
            inputs.stylix.homeModules.stylix
            ./home/default.nix
          ];
          home = {
            username = "${username}";
            homeDirectory = "/home/${username}";
            stateVersion = "26.05";
          };
        };
      }
      {
        users.mutableUsers = true;
        users.users.${username} = {
          isNormalUser = true;
          description = "${vars.gitUsername}";
          extraGroups = [
            "kvm" "adbusers" "docker" "libvirtd" "lp"
            "networkmanager" "scanner" "wheel" "dialout" "audio"
          ];
          shell = nixpkgs.legacyPackages.${system}.zsh;
          ignoreShellProgramCheck = true;
        };
        nix.settings.allowed-users = [ "${username}" ];
      }
      ./modules/misc
      ./modules/services
      ./modules/software
      ./modules/system
      ./modules/system/hardware_yourhostname.nix
    ];
  };
};

Step 7: Build and Switch

Now build and switch to your new configuration:

sudo nixos-rebuild switch --flake .#yourhostname

If you have git-ignored files (like variables.nix), use:

sudo nixos-rebuild switch --flake .#yourhostname --impure

First Build Tips

  • Takes time: First build downloads and builds many packages
  • Large download: Expect several GB of downloads
  • Check logs: Watch for errors during build
  • Don't panic: If it fails, read the error message carefully

Step 8: Reboot and Login

After successful build:

  1. Reboot your system: sudo reboot
  2. You should see SDDM login manager
  3. Login with your user account
  4. Hyprland should start automatically

Post-Installation

After logging in, proceed to First Steps to:

  • Set your password
  • Configure wallpapers
  • Learn keybindings
  • Customize your environment

Troubleshooting Installation

Build Fails with "file not found"

Make sure all files are tracked in git or use --impure flag:

git add -A
# or
sudo nixos-rebuild switch --flake .#yourhostname --impure

"No such configuration"

Check your hostname matches what you defined in flake.nix:

hostname  # Should match the name in flake.nix

Permission Errors

Ensure you're using sudo for nixos-rebuild:

sudo nixos-rebuild switch --flake .#yourhostname

NVIDIA Issues

If you have NVIDIA hardware, see NVIDIA configuration guide.

Hardware Detection Issues

If hardware isn't detected properly:

  1. Check your hardware config has all necessary modules
  2. Review boot.initrd.availableKernelModules
  3. Ensure filesystem UUIDs are correct

Alternative Installation Methods

From Existing NixOS

If you have an existing NixOS installation:

  1. Backup your current /etc/nixos/configuration.nix
  2. Follow steps above
  3. Can mix old config with NullOS by importing your old config as a module

Clean Install

For a fresh NixOS installation:

  1. Install NixOS using official installer
  2. Clone NullOS during first boot
  3. Follow this guide

Next Steps

Need help? Check Troubleshooting or open an issue on GitHub.

Clone this wiki locally