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" NIX_PATH="$NIX_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 You'll likely want to set a root password for your first boot using
164 the configuration files because you won't have a chance to enter a
165 password until after you reboot. You can initialize the root password
166 to an empty one with this line: (and of course don't forget to set
167 one once you've rebooted or to lock the account with
168 `sudo passwd -l root` if you use `sudo`)
169
170 ```nix
171 {
172 users.users.root.initialHashedPassword = "";
173 }
174 ```
175
1761. Build the NixOS closure and install it in the `system` profile:
177
178 ```ShellSession
179 $ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system
180 ```
181
1821. Change ownership of the `/nix` tree to root (since your Nix install
183 was probably single user):
184
185 ```ShellSession
186 $ sudo chown -R 0:0 /nix
187 ```
188
1891. Set up the `/etc/NIXOS` and `/etc/NIXOS_LUSTRATE` files:
190
191 `/etc/NIXOS` officializes that this is now a NixOS partition (the
192 bootup scripts require its presence).
193
194 `/etc/NIXOS_LUSTRATE` tells the NixOS bootup scripts to move
195 *everything* that's in the root partition to `/old-root`. This will
196 move your existing distribution out of the way in the very early
197 stages of the NixOS bootup. There are exceptions (we do need to keep
198 NixOS there after all), so the NixOS lustrate process will not
199 touch:
200
201 - The `/nix` directory
202
203 - The `/boot` directory
204
205 - Any file or directory listed in `/etc/NIXOS_LUSTRATE` (one per
206 line)
207
208 ::: {.note}
209 Support for `NIXOS_LUSTRATE` was added in NixOS 16.09. The act of
210 "lustrating" refers to the wiping of the existing distribution.
211 Creating `/etc/NIXOS_LUSTRATE` can also be used on NixOS to remove
212 all mutable files from your root partition (anything that's not in
213 `/nix` or `/boot` gets "lustrated" on the next boot.
214
215 lustrate /ˈlʌstreɪt/ verb.
216
217 purify by expiatory sacrifice, ceremonial washing, or some other
218 ritual action.
219 :::
220
221 Let's create the files:
222
223 ```ShellSession
224 $ sudo touch /etc/NIXOS
225 $ sudo touch /etc/NIXOS_LUSTRATE
226 ```
227
228 Let's also make sure the NixOS configuration files are kept once we
229 reboot on NixOS:
230
231 ```ShellSession
232 $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
233 ```
234
2351. Finally, move the `/boot` directory of your current distribution out
236 of the way (the lustrate process will take care of the rest once you
237 reboot, but this one must be moved out now because NixOS needs to
238 install its own boot files:
239
240 ::: {.warning}
241 Once you complete this step, your current distribution will no
242 longer be bootable! If you didn't get all the NixOS configuration
243 right, especially those settings pertaining to boot loading and root
244 partition, NixOS may not be bootable either. Have a USB rescue
245 device ready in case this happens.
246 :::
247
248 ```ShellSession
249 $ sudo mv -v /boot /boot.bak &&
250 sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
251 ```
252
253 Cross your fingers, reboot, hopefully you should get a NixOS prompt!
254
2551. If for some reason you want to revert to the old distribution,
256 you'll need to boot on a USB rescue disk and do something along
257 these lines:
258
259 ```ShellSession
260 # mkdir root
261 # mount /dev/sdaX root
262 # mkdir root/nixos-root
263 # mv -v root/* root/nixos-root/
264 # mv -v root/nixos-root/old-root/* root/
265 # mv -v root/boot.bak root/boot # We had renamed this by hand earlier
266 # umount root
267 # reboot
268 ```
269
270 This may work as is or you might also need to reinstall the boot
271 loader.
272
273 And of course, if you're happy with NixOS and no longer need the
274 old distribution:
275
276 ```ShellSession
277 sudo rm -rf /old-root
278 ```
279
2801. It's also worth noting that this whole process can be automated.
281 This is especially useful for Cloud VMs, where provider do not
282 provide NixOS. For instance,
283 [nixos-infect](https://github.com/elitak/nixos-infect) uses the
284 lustrate process to convert Digital Ocean droplets to NixOS from
285 other distributions automatically.