NixOS configuration basics: options and modules

Configuration File Structure#

The main NixOS configuration files are located in /etc/nixos/:

/etc/nixos/
├── configuration.nix      # 主配置文件
└── hardware-configuration.nix  # 硬件配置（自动生成）

Basic Configuration Structure#

{ config, pkgs, ... }:

{
  imports = [
    ./hardware-configuration.nix
  ];
  
  # 你的配置...
  
  system.stateVersion = "24.05"; # 示例初装版本；保留自己的初装值
}

Parameters:

config: the configuration state of the entire system
pkgs: the nixpkgs package set
...: allows additional arguments to be passed in, ignoring those not used

Common Configuration Options#

Boot Configuration

UEFI/systemd-boot and BIOS/GRUB are two examples; choose the one matching your installation mode. Verify GRUB's whole-disk target rather than blindly copying /dev/sda.

# UEFI 引导
boot.loader.systemd-boot.enable = true;
boot.loader.efi.canTouchEfiVariables = true;

# 传统 BIOS 引导
boot.loader.grub.enable = true;
boot.loader.grub.device = "/dev/sda";
boot.loader.grub.useOSProber = true;

Network Configuration

The static addresses below use a documentation-only address range, not a usable real network. Replace them with values for your network. When using desktop NetworkManager or static interface configuration, make clear which one manages a given interface.

# 主机名
networking.hostName = "workstation";

# NetworkManager（推荐桌面使用）
networking.networkmanager.enable = true;

# 静态 IP（服务器使用）
networking.interfaces.eth0.ipv4.addresses = [ {
  address = "192.0.2.10";
  prefixLength = 24;
} ];
networking.defaultGateway = "192.0.2.1";
networking.nameservers = [ "192.0.2.53" "192.0.2.54" ];

Localization

# 时区
time.timeZone = "Asia/Shanghai";

# 区域设置
i18n.defaultLocale = "zh_CN.UTF-8";
i18n.extraLocaleSettings = {
  LC_ADDRESS = "zh_CN.UTF-8";
  LC_IDENTIFICATION = "zh_CN.UTF-8";
  LC_MEASUREMENT = "zh_CN.UTF-8";
  LC_MONETARY = "zh_CN.UTF-8";
  LC_NAME = "zh_CN.UTF-8";
  LC_NUMERIC = "zh_CN.UTF-8";
  LC_PAPER = "zh_CN.UTF-8";
  LC_TELEPHONE = "zh_CN.UTF-8";
  LC_TIME = "zh_CN.UTF-8";
};

# 中文输入法
i18n.inputMethod = {
  enable = true;
  type = "fcitx5";
  fcitx5.addons = with pkgs; [
    fcitx5-rime
    fcitx5-chinese-addons
  ];
};

User Configuration

The docker group has elevated privileges; join it only when genuinely necessary. Before disabling SSH password authentication, verify that key-based login works so you do not lock yourself out of administrative access.

users.users.alice = {
  isNormalUser = true;
  description = "Alice";
  extraGroups = [ "networkmanager" "wheel" "docker" ];
  # 安装时交互设置密码；不要将明文密码写入公开配置。
  
  # 需要声明密码时，可使用部署时提供的 hashedPasswordFile。
  # 不要把密码哈希写进公开仓库或可读的 Nix store。
  
  # 设置默认 shell
  shell = pkgs.zsh;
  
  # SSH 公钥授权（不负责打开防火墙端口）
  openssh.authorizedKeys.keys = [
    "<完整 SSH 公钥，占位符不可直接使用>"
  ];
};

Package Management

# 系统级安装
environment.systemPackages = with pkgs; [
  vim
  git
  curl
  wget
  htop
  firefox
];

# 启用程序
programs.firefox.enable = true;
programs.git.enable = true;
programs.zsh.enable = true;

Service Configuration

# OpenSSH
services.openssh = {
  enable = true;
  settings = {
    PermitRootLogin = "no";
    PasswordAuthentication = false;
  };
};

# Docker
virtualisation.docker = {
  enable = true;
  enableOnBoot = true;
};

# 防火墙
networking.firewall.enable = true;
networking.firewall.allowedTCPPorts = [ 22 80 443 ];

Rebuild the System#

build only builds; dry-build only shows the build plan; test activates immediately; switch activates immediately and makes the result the boot default. None of these alone proves that services actually work correctly.

After changing the configuration, rebuild the system to apply it:

# 临时激活配置（会立即改变运行系统，但不设为启动默认项）
sudo nixos-rebuild test

# 应用配置
sudo nixos-rebuild switch

# 更新并重建
sudo nixos-rebuild switch --upgrade

Roll Back the Configuration

# 查看历史版本
sudo nixos-rebuild list-generations

# 切换到特定版本
sudo nix-env --profile /nix/var/nix/profiles/system --switch-generation 42
sudo /nix/var/nix/profiles/system/bin/switch-to-configuration switch

# 删除旧版本并回收（确认当前系统稳定、允许放弃旧回滚点后）
sudo nix-collect-garbage --delete-older-than 30d

Modular Configuration#

Split the configuration across multiple files:

/etc/nixos/
├── configuration.nix
├── hardware-configuration.nix
├── users.nix
├── desktop.nix
└── services.nix

Import them in configuration.nix:

imports = [
  ./hardware-configuration.nix
  ./users.nix
  ./desktop.nix
  ./services.nix
];

Example: users.nix

{ config, pkgs, ... }:

{
  users.users.alice = {
    isNormalUser = true;
    extraGroups = [ "wheel" "networkmanager" ];
  };
  
  users.users.bob = {
    isNormalUser = true;
    extraGroups = [ "networkmanager" ];
  };
}

Common Commands#

# 编辑配置
sudo nano /etc/nixos/configuration.nix

# 求值并列出将要构建/下载的路径（不执行构建）
nixos-rebuild dry-build

# 构建并预览激活操作（预览不保证包含全部影响）
nixos-rebuild dry-activate

# 查看当前配置选项值
nixos-option networking.hostName

# 搜索可用选项
man configuration.nix

References & further reading

Adapted from technical notes. Examples use generic names.