pyrox.dev
1# Installing from another Linux distribution {#sec-installing-from-other-distro}
2
3Because Nix (the package manager) & Nixpkgs (the Nix packages
4collection) can both be installed on any (most?) Linux distributions,
5they can be used to install NixOS in various creative ways. You can, for
6instance:
7
81. Install NixOS on another partition, from your existing Linux
9 distribution (without the use of a USB or optical device!)
10
111. Install NixOS on the same partition (in place!), from your existing
12 non-NixOS Linux distribution using `NIXOS_LUSTRATE`.
13
141. Install NixOS on your hard drive from the Live CD of any Linux
15 distribution.
16
17The first steps to all these are the same:
18
191. Install the Nix package manager:
20
21 Short version:
22
23 ```ShellSession
24 $ curl -L https://nixos.org/nix/install | sh
25 $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell
26 ```
27
28 More details in the [ Nix
29 manual](https://nixos.org/nix/manual/#chap-quick-start)
30
311. Switch to the NixOS channel:
32
33 If you've just installed Nix on a non-NixOS distribution, you will
34 be on the `nixpkgs` channel by default.
35
36 ```ShellSession
37 $ nix-channel --list
38 nixpkgs https://nixos.org/channels/nixpkgs-unstable
39 ```
40
41 As that channel gets released without running the NixOS tests, it
42 will be safer to use the `nixos-*` channels instead:
43
44 ```ShellSession
45 $ nix-channel --add https://nixos.org/channels/nixos-<version> nixpkgs
46 ```
47
48 Where `<version>` corresponds to the latest version available on [channels.nixos.org](https://channels.nixos.org/).
49
50 You may want to throw in a `nix-channel --update` for good measure.
51
521. Install the NixOS installation tools:
53
54 You'll need `nixos-generate-config` and `nixos-install`, but this
55 also makes some man pages and `nixos-enter` available, just in case
56 you want to chroot into your NixOS partition. NixOS installs these
57 by default, but you don't have NixOS yet..
58
59 ```ShellSession
60 $ nix-env -f '<nixpkgs>' -iA nixos-install-tools
61 ```
62
631. ::: {.note}
64 The following 5 steps are only for installing NixOS to another
65 partition. For installing NixOS in place using `NIXOS_LUSTRATE`,
66 skip ahead.
67 :::
68
69 Prepare your target partition:
70
71 At this point it is time to prepare your target partition. Please
72 refer to the partitioning, file-system creation, and mounting steps
73 of [](#sec-installation)
74
75 If you're about to install NixOS in place using `NIXOS_LUSTRATE`
76 there is nothing to do for this step.
77
781. Generate your NixOS configuration:
79
80 ```ShellSession
81 $ sudo `which nixos-generate-config` --root /mnt
82 ```
83
84 You'll probably want to edit the configuration files. Refer to the
85 `nixos-generate-config` step in [](#sec-installation) for more
86 information.
87
88 Consider setting up the NixOS bootloader to give you the ability to
89 boot on your existing Linux partition. For instance, if you're
90 using GRUB and your existing distribution is running Ubuntu, you may
91 want to add something like this to your `configuration.nix`:
92
93 ```nix
94 {
95 boot.loader.grub.extraEntries = ''
96 menuentry "Ubuntu" {
97 search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
98 configfile "($ubuntu)/boot/grub/grub.cfg"
99 }
100 '';
101 }
102 ```
103
104 (You can find the appropriate UUID for your partition in
105 `/dev/disk/by-uuid`)
106
1071. Create the `nixbld` group and user on your original distribution:
108
109 ```ShellSession
110 $ sudo groupadd -g 30000 nixbld
111 $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld
112 ```
113
1141. Download/build/install NixOS:
115
116 ::: {.warning}
117 Once you complete this step, you might no longer be able to boot on
118 existing systems without the help of a rescue USB drive or similar.
119 :::
120
121 ::: {.note}
122 On some distributions there are separate PATHS for programs intended
123 only for root. In order for the installation to succeed, you might
124 have to use `PATH="$PATH:/usr/sbin:/sbin"` in the following command.
125 :::
126
127 ```ShellSession
128 $ sudo PATH="$PATH" `which nixos-install` --root /mnt
129 ```
130
131 Again, please refer to the `nixos-install` step in
132 [](#sec-installation) for more information.
133
134 That should be it for installation to another partition!
135
1361. Optionally, you may want to clean up your non-NixOS distribution:
137
138 ```ShellSession
139 $ sudo userdel nixbld
140 $ sudo groupdel nixbld
141 ```
142
143 If you do not wish to keep the Nix package manager installed either,
144 run something like `sudo rm -rv ~/.nix-* /nix` and remove the line
145 that the Nix installer added to your `~/.profile`.
146
1471. ::: {.note}
148 The following steps are only for installing NixOS in place using
149 `NIXOS_LUSTRATE`:
150 :::
151
152 Generate your NixOS configuration:
153
154 ```ShellSession
155 $ sudo `which nixos-generate-config`
156 ```
157
158 Note that this will place the generated configuration files in
159 `/etc/nixos`. You'll probably want to edit the configuration files.
160 Refer to the `nixos-generate-config` step in
161 [](#sec-installation) for more information.
162
163 ::: {.note}
164 On [UEFI](https://en.wikipedia.org/wiki/UEFI) systems, check that your `/etc/nixos/hardware-configuration.nix` did the right thing with the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition).
165 In NixOS, by default, both [systemd-boot](https://systemd.io/BOOT/) and [grub](https://www.gnu.org/software/grub/index.html) expect it to be mounted on `/boot`.
166 However, the configuration generator bases its [](#opt-fileSystems) configuration on the current mount points at the time it is run.
167 If the current system and NixOS's bootloader configuration don't agree on where the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition) is to be mounted, you'll need to manually alter the mount point in `hardware-configuration.nix` before building the system closure.
168 :::
169
170 ::: {.note}
171 The lustrate process will not work if the [](#opt-boot.initrd.systemd.enable) option is set to `true`.
172 If you want to use this option, wait until after the first boot into the NixOS system to enable it and rebuild.
173 :::
174
175 You'll likely want to set a root password for your first boot using
176 the configuration files because you won't have a chance to enter a
177 password until after you reboot. You can initialize the root password
178 to an empty one with this line: (and of course don't forget to set
179 one once you've rebooted or to lock the account with
180 `sudo passwd -l root` if you use `sudo`)
181
182 ```nix
183 { users.users.root.initialHashedPassword = ""; }
184 ```
185
1861. Build the NixOS closure and install it in the `system` profile:
187
188 ```ShellSession
189 $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system
190 ```
191
1921. Change ownership of the `/nix` tree to root (since your Nix install
193 was probably single user):
194
195 ```ShellSession
196 $ sudo chown -R 0:0 /nix
197 ```
198
1991. Set up the `/etc/NIXOS` and `/etc/NIXOS_LUSTRATE` files:
200
201 `/etc/NIXOS` officializes that this is now a NixOS partition (the
202 bootup scripts require its presence).
203
204 `/etc/NIXOS_LUSTRATE` tells the NixOS bootup scripts to move
205 *everything* that's in the root partition to `/old-root`. This will
206 move your existing distribution out of the way in the very early
207 stages of the NixOS bootup. There are exceptions (we do need to keep
208 NixOS there after all), so the NixOS lustrate process will not
209 touch:
210
211 - The `/nix` directory
212
213 - The `/boot` directory
214
215 - Any file or directory listed in `/etc/NIXOS_LUSTRATE` (one per
216 line)
217
218 ::: {.note}
219 The act of "lustrating" refers to the wiping of the existing distribution.
220 Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove
221 all mutable files from your root partition (anything that's not in
222 `/nix` or `/boot` gets "lustrated" on the next boot.
223
224 lustrate /ˈlʌstreɪt/ verb.
225
226 purify by expiatory sacrifice, ceremonial washing, or some other
227 ritual action.
228 :::
229
230 Let's create the files:
231
232 ```ShellSession
233 $ sudo touch /etc/NIXOS
234 $ sudo touch /etc/NIXOS_LUSTRATE
235 ```
236
237 Let's also make sure the NixOS configuration files are kept once we
238 reboot on NixOS:
239
240 ```ShellSession
241 $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
242 ```
243
2441. Finally, install NixOS's boot system, backing up the current boot system's files in the process.
245
246 The details of this step can vary depending on the bootloader configuration in NixOS and the bootloader in use by the current system.
247
248 The commands below should work for:
249
250 - [BIOS](https://en.wikipedia.org/wiki/BIOS) systems.
251
252 - [UEFI](https://en.wikipedia.org/wiki/UEFI) systems where both the current system and NixOS mount the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition) on `/boot`.
253 Both [systemd-boot](https://systemd.io/BOOT/) and [grub](https://www.gnu.org/software/grub/index.html) expect this by default in NixOS, but other distributions vary.
254
255 ::: {.warning}
256 Once you complete this step, your current distribution will no longer be bootable!
257 If you didn't get all the NixOS configuration right, especially those settings pertaining to boot loading and root partition, NixOS may not be bootable either.
258 Have a USB rescue device ready in case this happens.
259 :::
260
261 ::: {.warning}
262 On [UEFI](https://en.wikipedia.org/wiki/UEFI) systems, anything on the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition) will be removed by these commands, such as other coexisting OS's bootloaders.
263 :::
264
265 ```ShellSession
266 $ sudo mkdir /boot.bak && sudo mv /boot/* /boot.bak &&
267 sudo NIXOS_INSTALL_BOOTLOADER=1 /nix/var/nix/profiles/system/bin/switch-to-configuration boot
268 ```
269
270 Cross your fingers, reboot, hopefully you should get a NixOS prompt!
271
272 In other cases, most commonly where the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition) of the current system is instead mounted on `/boot/efi`, the goal is to:
273
274 - Make sure `/boot` (and the [EFI System Partition](https://en.wikipedia.org/wiki/EFI_system_partition), if mounted elsewhere) are mounted how the NixOS configuration would mount them.
275
276 - Clear them of files related to the current system, backing them up outside of `/boot`.
277 NixOS will move the backups into `/old-root` along with everything else when it first boots.
278
279 - Instruct the NixOS closure built earlier to install its bootloader with:
280 ```ShellSession
281 sudo NIXOS_INSTALL_BOOTLOADER=1 /nix/var/nix/profiles/system/bin/switch-to-configuration boot
282 ```
283
2841. If for some reason you want to revert to the old distribution,
285 you'll need to boot on a USB rescue disk and do something along
286 these lines:
287
288 ```ShellSession
289 # mkdir root
290 # mount /dev/sdaX root
291 # mkdir root/nixos-root
292 # mv -v root/* root/nixos-root/
293 # mv -v root/nixos-root/old-root/* root/
294 # mv -v root/boot.bak root/boot # We had renamed this by hand earlier
295 # umount root
296 # reboot
297 ```
298
299 This may work as is or you might also need to reinstall the boot
300 loader.
301
302 And of course, if you're happy with NixOS and no longer need the
303 old distribution:
304
305 ```ShellSession
306 sudo rm -rf /old-root
307 ```
308
3091. It's also worth noting that this whole process can be automated.
310 This is especially useful for Cloud VMs, where provider do not
311 provide NixOS. For instance,
312 [nixos-infect](https://github.com/elitak/nixos-infect) uses the
313 lustrate process to convert Digital Ocean droplets to NixOS from
314 other distributions automatically.