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 {
184 users.users.root.initialHashedPassword = "";
185 }
186 ```
187
1881. Build the NixOS closure and install it in the `system` profile:
189
190 ```ShellSession
191 $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system
192 ```
193
1941. Change ownership of the `/nix` tree to root (since your Nix install
195 was probably single user):
196
197 ```ShellSession
198 $ sudo chown -R 0:0 /nix
199 ```
200
2011. Set up the `/etc/NIXOS` and `/etc/NIXOS_LUSTRATE` files:
202
203 `/etc/NIXOS` officializes that this is now a NixOS partition (the
204 bootup scripts require its presence).
205
206 `/etc/NIXOS_LUSTRATE` tells the NixOS bootup scripts to move
207 *everything* that's in the root partition to `/old-root`. This will
208 move your existing distribution out of the way in the very early
209 stages of the NixOS bootup. There are exceptions (we do need to keep
210 NixOS there after all), so the NixOS lustrate process will not
211 touch:
212
213 - The `/nix` directory
214
215 - The `/boot` directory
216
217 - Any file or directory listed in `/etc/NIXOS_LUSTRATE` (one per
218 line)
219
220 ::: {.note}
221 The act of "lustrating" refers to the wiping of the existing distribution.
222 Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove
223 all mutable files from your root partition (anything that's not in
224 `/nix` or `/boot` gets "lustrated" on the next boot.
225
226 lustrate /ˈlʌstreɪt/ verb.
227
228 purify by expiatory sacrifice, ceremonial washing, or some other
229 ritual action.
230 :::
231
232 Let's create the files:
233
234 ```ShellSession
235 $ sudo touch /etc/NIXOS
236 $ sudo touch /etc/NIXOS_LUSTRATE
237 ```
238
239 Let's also make sure the NixOS configuration files are kept once we
240 reboot on NixOS:
241
242 ```ShellSession
243 $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
244 ```
245
2461. Finally, install NixOS's boot system, backing up the current boot system's files in the process.
247
248 The details of this step can vary depending on the bootloader configuration in NixOS and the bootloader in use by the current system.
249
250 The commands below should work for:
251
252 - [BIOS](https://en.wikipedia.org/wiki/BIOS) systems.
253
254 - [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`.
255 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.
256
257 ::: {.warning}
258 Once you complete this step, your current distribution will no longer be bootable!
259 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.
260 Have a USB rescue device ready in case this happens.
261 :::
262
263 ::: {.warning}
264 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.
265 :::
266
267 ```ShellSession
268 $ sudo mkdir /boot.bak && sudo mv /boot/* /boot.bak &&
269 sudo NIXOS_INSTALL_BOOTLOADER=1 /nix/var/nix/profiles/system/bin/switch-to-configuration boot
270 ```
271
272 Cross your fingers, reboot, hopefully you should get a NixOS prompt!
273
274 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:
275
276 - 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.
277
278 - Clear them of files related to the current system, backing them up outside of `/boot`.
279 NixOS will move the backups into `/old-root` along with everything else when it first boots.
280
281 - Instruct the NixOS closure built earlier to install its bootloader with:
282 ```ShellSession
283 sudo NIXOS_INSTALL_BOOTLOADER=1 /nix/var/nix/profiles/system/bin/switch-to-configuration boot
284 ```
285
2861. If for some reason you want to revert to the old distribution,
287 you'll need to boot on a USB rescue disk and do something along
288 these lines:
289
290 ```ShellSession
291 # mkdir root
292 # mount /dev/sdaX root
293 # mkdir root/nixos-root
294 # mv -v root/* root/nixos-root/
295 # mv -v root/nixos-root/old-root/* root/
296 # mv -v root/boot.bak root/boot # We had renamed this by hand earlier
297 # umount root
298 # reboot
299 ```
300
301 This may work as is or you might also need to reinstall the boot
302 loader.
303
304 And of course, if you're happy with NixOS and no longer need the
305 old distribution:
306
307 ```ShellSession
308 sudo rm -rf /old-root
309 ```
310
3111. It's also worth noting that this whole process can be automated.
312 This is especially useful for Cloud VMs, where provider do not
313 provide NixOS. For instance,
314 [nixos-infect](https://github.com/elitak/nixos-infect) uses the
315 lustrate process to convert Digital Ocean droplets to NixOS from
316 other distributions automatically.