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

The ’nixos-rebuild’ command is used to reconfigure a NixOS machine. It allows users to build and switch to a new configuration, rollback changes, install updates, and perform other operations related to system configuration. In this article, we will illustrate each of these use cases with examples.

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

Code:

sudo nixos-rebuild switch

Motivation: This use case is commonly used when users want to apply changes to their NixOS configuration and make them the default configuration for future boots. By using this command, NixOS will build and switch to the new configuration specified in the NixOS configuration file.

Explanation: The command ‘sudo nixos-rebuild switch’ rebuilds the NixOS configuration and switches to the newly built configuration. It reads the configuration file located at ‘/etc/nixos/configuration.nix’ by default. The ‘sudo’ command is used to execute the ’nixos-rebuild’ command with administrative privileges.

Example output:

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

switching to the new 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: This use case is useful when users want to specify a custom name for the boot entry of the newly built configuration. By using the ‘-p’ option followed by a name, users can easily identify and select the desired configuration during system boot.

Explanation: The ‘-p’ option followed by the desired name allows users to specify a custom name for a boot entry. The ’nixos-rebuild’ command will build and switch to the new configuration, making it the boot default with the specified name.

Example output:

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

switching to the new 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: This use case is important when users want to not only apply changes to the NixOS configuration but also upgrade the system with the latest package versions available. By using the ‘–upgrade’ option, users can ensure that their system is up to date.

Explanation: The ‘–upgrade’ option instructs ’nixos-rebuild’ to also perform a system upgrade when building and switching to the new configuration. This ensures that the latest package versions are installed.

Example output:

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

switching to the new configuration...

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

Code:

sudo nixos-rebuild switch --rollback

Motivation: This use case is useful when users want to revert to the previous generation of the NixOS configuration. It allows users to roll back any changes made to the configuration and restore their system to a previous state.

Explanation: The ‘–rollback’ option instructs ’nixos-rebuild’ to switch to the previous generation of the configuration. This will undo any changes made to the current configuration and revert the system to the previous state.

Example output:

rolling back to the previous configuration...
switching to the previous generation...

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

Code:

sudo nixos-rebuild boot

Motivation: This use case is helpful when users want to build the new configuration but don’t want to switch to it immediately. It allows users to preview the new configuration before making it the default for future boots.

Explanation: The ’nixos-rebuild boot’ command builds the new configuration but does not switch to it. This means that the current configuration remains active, and the new configuration is built and stored, ready to be switched to at a later time.

Example output:

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

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: This use case is helpful when users want to test a new configuration without making it the default for future boots. It allows users to verify the correctness of the new configuration before committing to it.

Explanation: The ’nixos-rebuild test’ command builds and activates the new configuration, similar to ’nixos-rebuild switch’, but without creating a boot entry. This is usually used for testing purposes to verify that the new configuration works as expected.

Example output:

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

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

Code:

sudo nixos-rebuild build-vm

Motivation: This use case is useful when users want to build the NixOS configuration and test it within a virtual machine environment. It allows users to ensure that the configuration is compatible with the virtualized environment.

Explanation: The ’nixos-rebuild build-vm’ command builds the configuration and creates a virtual machine image based on the specified configuration. This image can then be used to run the configuration within a virtual machine environment.

Example output:

building Nix...
building the system configuration...
creating a virtual machine image...

Conclusion:

The ’nixos-rebuild’ command provides a range of options to reconfigure a NixOS machine. Whether it’s switching to a new configuration, rolling back changes, installing updates, or testing configurations, ’nixos-rebuild’ offers the flexibility and control needed to manage NixOS effectively. By understanding and utilizing these different use cases, users can easily customize and maintain their NixOS systems.