How to use the command 'nixos-rebuild' (with examples)

The nixos-rebuild command is an essential tool for NixOS users, allowing them to manage system configurations effectively. NixOS uses a unique approach in which its entire system configuration is defined in a single declarative file, configuration.nix. The nixos-rebuild command interacts with this configuration file to build and switch to new system configurations, apply updates, roll back changes, and even test configurations in a virtual environment. This makes it an incredibly powerful and flexible tool for managing NixOS systems.

Use case 1: Build and switch to the new configuration, making it the boot default

Code:

sudo nixos-rebuild switch

Motivation:

When you make changes to your system configuration file in NixOS, such as installing new packages or modifying system settings, you must apply these changes for them to take effect. The switch sub-command compiles the new configuration and directly applies it, updating the system. This makes it the default boot option, ensuring that your system boots with this configuration in the future.

Explanation:

• sudo: Grants administrative privileges necessary for making system-wide changes.
• nixos-rebuild: The command to rebuild and apply the system configuration.
• switch: Builds the new configuration and immediately activates it as the running system.

Example output:

building Nix...
building the system configuration...
activating the configuration...

Use case 2: Build and switch to the new configuration, making it the boot default and naming the boot entry

Code:

sudo nixos-rebuild switch -p name

Motivation:

Naming boot entries can be particularly useful if you manage multiple configurations or need a reminder of what a specific configuration represents. By assigning a name, you can easily identify and select configurations from the bootloader menu.

Explanation:

• -p name: Specifies the profile name for this configuration. This name will appear in the bootloader menu.

Example output:

building Nix...
building the system configuration...
activating the configuration...
new boot entry name: my-custom-configuration

Use case 3: Build and switch to the new configuration, making it the boot default and installing updates

Code:

sudo nixos-rebuild switch --upgrade

Motivation:

When keeping a NixOS system up to date, it’s crucial to apply the latest software patches and security updates. This command facilitates both building and switching to the new configuration while also pulling the latest updates from the NixOS channels, ensuring that your system runs the most recent stable software.

Explanation:

• --upgrade: Updates the list of available Nix packages to the latest version from the configured channels before building the configuration.

Example output:

updating Nix channel...
building Nix...
building the system configuration...
activating the configuration...

Use case 4: Rollback changes to the configuration, switching to the previous generation

Code:

sudo nixos-rebuild switch --rollback

Motivation:

If you encounter issues after applying a new configuration, rolling back to a previous, working state is a lifesaver. This feature preserves system stability by allowing you to revert unwanted changes.

Explanation:

• --rollback: Switches to the configuration state prior to the latest changes, effectively undoing recent updates or modifications.

Example output:

activating the fallback configuration...

Use case 5: Build the new configuration and make it the boot default without switching to it

Code:

sudo nixos-rebuild boot

Motivation:

There are instances where you might want to build a configuration and set it as the default boot option without immediately switching your currently running system. This can be useful during off-hours where downtime isn’t acceptable but a reboot is scheduled for later.

Explanation:

• boot: Prepares the system to use the new configuration on the next system restart but does not apply the changes to the currently running system.

Example output:

building Nix...
building the system configuration...
updating the bootloader...

Use case 6: Build and activate the new configuration, but don’t make a boot entry (for testing purposes)

Code:

sudo nixos-rebuild test

Motivation:

Before committing a configuration as the default boot option, it’s often wise to test it. This command allows you to temporarily apply changes to the running system without altering the boot setup, useful for testing configurations that might not yet be stable.

Explanation:

• test: Activates the configuration temporarily for the current session only, disregarding boot configurations.

Example output:

building Nix...
building the system configuration...
activating the configuration...
changes are temporary and will not persist on reboot

Use case 7: Build the configuration and open it in a virtual machine

Code:

sudo nixos-rebuild build-vm

Motivation:

Testing configurations in a virtual environment is extremely useful for ensuring that changes won’t disrupt your production system. This approach helps envisage changes in a safe, isolated environment without impacting the host system.

Explanation:

• build-vm: Compiles the system and encapsulates it in a virtual machine, offering a sandboxed environment for testing.

Example output:

building Nix...
creating the virtual machine image...
starting VM...
connecting to VM...

Conclusion:

The nixos-rebuild command is a versatile tool that simplifies the management of NixOS system configurations. Each use case demonstrates a unique aspect of what makes NixOS powerful and flexible in terms of maintaining system states, testing changes, and ensuring stability. Whether you are updating your system, rolling back recent changes, or testing new configurations, nixos-rebuild provides the necessary options to do so efficiently.