···

       
2
       
2
       
 
       


     

       
3
       
3
       
 
       
Nixpkgs contains a variety of modules to build custom images for different virtualization platforms and cloud providers, such as e.g. `amazon-image.nix` and `proxmox-lxc.nix`.

     

       
4
       
4
       
 
       


     

       
5
       
5
       
-
       
While those can be imported individually, `system.build.images` provides an attribute set mapping variant names to image derivations. Available variants are defined - end extendable - in `image.modules`, an attribute set mapping variant names to a list of NixOS modules.

     

       
5
       
5
       
+
       
While those can be imported directly, `system.build.images` provides an attribute set mapping variant names to image derivations. Available variants are defined - end extendable - in `image.modules`, an attribute set mapping variant names to NixOS modules.

     

       
6
       
6
       
 
       


     

       
7
       
7
       
-
       
All of those images can be built via both, their `system.build.image` attribute, and the CLI `nixos-rebuild build-image`. To build i.e. an Amazon image from your existing NixOS configuration:

     

       
7
       
7
       
+
       
All of those images can be built via both, their `system.build.image` attribute and the `nixos-rebuild build-image` command.

     

       
8
       
8
       
+
       


     

       
9
       
9
       
+
       
For example, to build an Amazon image from your existing NixOS configuration, run:

     

       
8
       
10
       
 
       


     

       
9
       
11
       
 
       
```ShellSession

     

       
10
       
12
       
 
       
$ nixos-rebuild build-image --image-variant amazon

     

       
11
       
11
       
-
       
$ ls result

     

       
12
       
12
       
-
       
nixos-image-amazon-25.05pre-git-x86_64-linux.vhd  nix-support

     

       
13
       
13
       
+
       
[...]

     

       
14
       
14
       
+
       
Done. The disk image can be found in /nix/store/[hash]-nixos-image-amazon-25.05pre-git-x86_64-linux/nixos-image-amazon-25.05pre-git-x86_64-linux.vpc

     

       
13
       
15
       
 
       
```

     

       
14
       
16
       
 
       


     

       
15
       
17
       
 
       
To get a list of all variants available, run `nixos-rebuild build-image` without arguments.

     

       
18
       
18
       
+
       


     

       
19
       
19
       
+
       
::: {.example #ex-nixos-rebuild-build-image-customize}

     

       
16
       
20
       
 
       


     

       
17
       
21
       
 
       
## Customize specific image variants {#sec-image-nixos-rebuild-build-image-customize}

     

       
18
       
22
       
 
       


     

       
19
       
19
       
-
       
The `image.modules` option can be used to set specific options per image variant, in a similar fashion as [specialisations](options.html#opt-specialisation) for generic nixos configurations.

     

       
23
       
23
       
+
       
The `image.modules` option can be used to set specific options per image variant, in a similar fashion as [specialisations](options.html#opt-specialisation) for generic NixOS configurations.

     

       
20
       
24
       
 
       


     

       
21
       
21
       
-
       
E.g. images for the cloud provider Linode use `grub2` as a bootloader by default. If you are using `systemd-boot` on other platforms and want to disable it for Linode onlz, you could use the following options:

     

       
25
       
25
       
+
       
E.g. images for the cloud provider Linode use `grub2` as a bootloader by default. If you are using `systemd-boot` on other platforms and want to disable it for Linode only, you could use the following options:

     

       
22
       
26
       
 
       


     

       
23
       
27
       
 
       
``` nix

     

       
24
       
28
       
 
       
  image.modules.linode = {

     

···

       
146
       
146
       
 
       
  "ex-config": [

     

       
147
       
147
       
 
       
    "index.html#ex-config"

     

       
148
       
148
       
 
       
  ],

     

       
149
       
149
       
+
       
  "ex-nixos-rebuild-build-image-customize": [

     

       
150
       
150
       
+
       
    "index.html#ex-nixos-rebuild-build-image-customize"

     

       
151
       
151
       
+
       
  ],

     

       
149
       
152
       
 
       
  "sec-installation-additional-notes": [

     

       
150
       
153
       
 
       
    "index.html#sec-installation-additional-notes"

     

       
151
       
154
       
 
       
  ],