-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathNixOS-Manual-Version-20.09.html
7710 lines (7533 loc) · 839 KB
/
NixOS-Manual-Version-20.09.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<!-- saved from url=(0038)https://nixos.org/manual/nixos/stable/ -->
<html lang="en" class="with-js"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>NixOS - NixOS 20.09 manual</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
<meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1.0">
<style class="anchorjs"></style><link rel="stylesheet" href="./NixOS-Manual-Version-20.09_files/index.css" type="text/css">
<link rel="shortcut icon" type="image/png" href="https://nixos.org/favicon.png">
<meta name="google-site-verification" content="ir-07nYvo3u3x_VmkTO1wCfYJ8uC-SrVBGR7hZgqPSE">
<script>
var html = document.documentElement;
html.className = html.className.replace("without-js", "with-js");
</script><style>@media print {#ghostery-tracker-tally {display:none !important}}</style>
<script type="text/javascript" src="./NixOS-Manual-Version-20.09_files/jquery.min.js"></script>
<link rel="canonical" url="https://nixos.org/manual/nixos/stable">
</head>
<body data-nixos-channels="[{"channel":"unstable","version":"21.05"},{"channel":"stable","version":"20.09"}]">
<header>
<div>
<h1><a href="https://nixos.org/">NixOS</a></h1>
<nav style="display: none;">
<ul>
<li class=""> <a href="https://nixos.org/explore.html">Explore</a></li>
<li class=""> <a href="https://nixos.org/download.html">Download</a></li>
<li class=""> <a href="https://nixos.org/learn.html">Learn</a></li>
<li class=""> <a href="https://nixos.org/community.html">Community</a></li>
<li class=""> <a href="https://nixos.org/governance.html">Governance</a></li>
<li class=""> <a href="https://nixos.org/donate.html">Donate</a></li>
<li class=" activesearch"> <a href="https://search.nixos.org/packages">Search</a></li> </ul>
</nav>
</div>
<button class="menu-toggle">Toggle the menu</button></header>
<main>
<section class="generic-layout docbook-page"><script xmlns="http://www.w3.org/1999/xhtml" src="./NixOS-Manual-Version-20.09_files/highlight.pack.js" type="text/javascript" xml:space="preserve"></script><script xmlns="http://www.w3.org/1999/xhtml" src="./NixOS-Manual-Version-20.09_files/loader.js" type="text/javascript" xml:space="preserve"></script><link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" type="text/css" href="./NixOS-Manual-Version-20.09_files/overrides.css"><link xmlns="http://www.w3.org/1999/xhtml" rel="stylesheet" type="text/css" href="./NixOS-Manual-Version-20.09_files/mono-blue.css"><div xmlns="http://www.w3.org/1999/xhtml" class="page-header"><h1 id="nixos-manual"><a id="book-nixos-manual" shape="rect"></a>NixOS Manual<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#nixos-manual" aria-label="Anchor link for: nixos manual" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h1><h2 id="version-20-09">Version 20.09
<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#version-20-09" aria-label="Anchor link for: version 20 09" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div><ul xmlns="http://www.w3.org/1999/xhtml" class="hidden"><li class="next"><a accesskey="n" href="https://nixos.org/manual/nixos/stable/options.html">Appendix A. Configuration Options →</a></li></ul><div xmlns="http://www.w3.org/1999/xhtml" class="docbook"><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="preface"><a href="https://nixos.org/manual/nixos/stable/index.html#preface" shape="rect">Preface</a></span></dt><dt><span class="part"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-installation" shape="rect">I. Installation</a></span></dt><dd><dl><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-obtaining" shape="rect">1. Obtaining NixOS</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" shape="rect">2. Installing NixOS</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-changing-config" shape="rect">3. Changing the Configuration</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-upgrading" shape="rect">4. Upgrading NixOS</a></span></dt></dl></dd><dt><span class="part"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-configuration" shape="rect">II. Configuration</a></span></dt><dd><dl><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax" shape="rect">5. Configuration Syntax</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-package-management" shape="rect">6. Package Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-user-management" shape="rect">7. User Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-file-systems" shape="rect">8. File Systems</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-x11" shape="rect">9. X Window System</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-gpu-accel" shape="rect">10. GPU acceleration</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-xfce" shape="rect">11. Xfce Desktop Environment</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-networking" shape="rect">12. Networking</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-kernel-config" shape="rect">13. Linux Kernel</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#chap-pantheon" shape="rect">14. Pantheon Desktop</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-matomo" shape="rect">15. Matomo</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-nextcloud" shape="rect">16. Nextcloud</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-jitsi-meet" shape="rect">17. Jitsi Meet</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-grocy" shape="rect">18. Grocy</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-networking-yggdrasil" shape="rect">19. Yggdrasil</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-prosody" shape="rect">20. Prosody</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-prometheus-exporters" shape="rect">21. Prometheus exporters</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-weechat" shape="rect">22. WeeChat</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-taskserver" shape="rect">23. Taskserver</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-matrix" shape="rect">24. Matrix</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-gitlab" shape="rect">25. Gitlab</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-mailman" shape="rect">26. Mailman</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#trezor" shape="rect">27. Trezor</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-emacs" shape="rect">28. Emacs</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-flatpak" shape="rect">29. Flatpak</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-postgresql" shape="rect">30. PostgreSQL</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-foundationdb" shape="rect">31. FoundationDB</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-borgbase" shape="rect">32. BorgBackup</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-hidepid" shape="rect">33. Hiding process information</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-security-acme" shape="rect">34. SSL/TLS Certificates with ACME</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-programs-zsh-ohmyzsh" shape="rect">35. Oh my ZSH</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-program-plotinus" shape="rect">36. Plotinus</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-programs-digitalbitbox" shape="rect">37. Digital Bitbox</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-input-methods" shape="rect">38. Input Methods</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-profiles" shape="rect">39. Profiles</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-kubernetes" shape="rect">40. Kubernetes</a></span></dt></dl></dd><dt><span class="part"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-running" shape="rect">III. Administration</a></span></dt><dd><dl><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-systemctl" shape="rect">41. Service Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-rebooting" shape="rect">42. Rebooting and Shutting Down</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-user-sessions" shape="rect">43. User Sessions</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-cgroups" shape="rect">44. Control Groups</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-logging" shape="rect">45. Logging</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-nix-gc" shape="rect">46. Cleaning the Nix Store</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-containers" shape="rect">47. Container Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-troubleshooting" shape="rect">48. Troubleshooting</a></span></dt></dl></dd><dt><span class="part"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-development" shape="rect">IV. Development</a></span></dt><dd><dl><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-getting-sources" shape="rect">49. Getting the Sources</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules" shape="rect">50. Writing NixOS Modules</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-building-parts" shape="rect">51. Building Specific Parts of NixOS</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-writing-documentation" shape="rect">52. Writing NixOS Documentation</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-building-cd" shape="rect">53. Building Your Own NixOS CD</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests" shape="rect">54. NixOS Tests</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-testing-installer" shape="rect">55. Testing the Installer</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-releases" shape="rect">56. Releases</a></span></dt></dl></dd><dt><span class="appendix"><a href="https://nixos.org/manual/nixos/stable/options.html" shape="rect">A. Configuration Options</a></span></dt><dt><span class="appendix"><a href="https://nixos.org/manual/nixos/stable/release-notes.html" shape="rect">B. Release Notes</a></span></dt></dl></div><section class="preface"><div class="titlepage"><div><div><div class="page-header"><h1 id="preface" class="title">Preface<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#preface" aria-label="Anchor link for: preface" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h1></div></div></div></div><p>
This manual describes how to install, use and extend NixOS, a Linux
distribution based on the purely functional package management system
<a class="link" href="https://nixos.org/nix" target="_top" shape="rect">Nix</a>, that is composed
using modules and packages defined in the
<a class="link" href="https://nixos.org/nixpkgs" target="_top" shape="rect">Nixpkgs</a> project.
</p><p>
Additional information regarding the Nix package manager and the Nixpkgs
project can be found in respectively the
<a class="link" href="https://nixos.org/nix/manual" target="_top" shape="rect">Nix manual</a> and the
<a class="link" href="https://nixos.org/nixpkgs/manual" target="_top" shape="rect">Nixpkgs manual</a>.
</p><p>
If you encounter problems, please report them on the
<code class="literal"><a class="literal" href="https://discourse.nixos.org/" target="_top" shape="rect">Discourse</a></code> or
on the <a class="link" href="irc://irc.freenode.net/#nixos" target="_top" shape="rect">
<code class="literal">#nixos</code> channel on Freenode</a>. Bugs should be
reported in
<a class="link" href="https://github.com/NixOS/nixpkgs/issues" target="_top" shape="rect">NixOS’
GitHub issue tracker</a>.
</p><div class="alert alert-info"><strong>Note:</strong>
Commands prefixed with <code class="literal">#</code> have to be run as root, either
requiring to login as root user or temporarily switching to it using
<code class="literal">sudo</code> for example.
</div></section><div class="part"><div class="titlepage"><div><div><div class="page-header"><h1 id="ch-installation" class="title">Part I. Installation<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#ch-installation" aria-label="Anchor link for: ch installation" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h1></div></div></div></div><div class="partintro"><div></div><p>
This section describes how to obtain, install, and configure NixOS for
first-time use.
</p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-obtaining" shape="rect">1. Obtaining NixOS</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" shape="rect">2. Installing NixOS</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-changing-config" shape="rect">3. Changing the Configuration</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-upgrading" shape="rect">4. Upgrading NixOS</a></span></dt></dl></div></div><section class="chapter"><div class="titlepage"><div><div><h2 id="sec-obtaining" class="title">Chapter 1. Obtaining NixOS<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-obtaining" aria-label="Anchor link for: sec obtaining" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
NixOS ISO images can be downloaded from the
<a class="link" href="https://nixos.org/nixos/download.html" target="_top" shape="rect">NixOS download
page</a>. There are a number of installation options. If you happen to
have an optical drive and a spare CD, burning the image to CD and booting
from that is probably the easiest option. Most people will need to prepare a
USB stick to boot from. <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb" title="2.5.1. Booting from a USB Drive" shape="rect">Section 2.5.1, “Booting from a USB Drive”</a> describes the
preferred method to prepare a USB stick. A number of alternative methods are
presented in the
<a class="link" href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media" target="_top" shape="rect">NixOS
Wiki</a>.
</p><p>
As an alternative to installing NixOS yourself, you can get a running NixOS
system through several other means:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Using virtual appliances in Open Virtualization Format (OVF) that can be
imported into VirtualBox. These are available from the
<a class="link" href="https://nixos.org/nixos/download.html" target="_top" shape="rect">NixOS download
page</a>.
</p></li><li class="listitem"><p>
Using AMIs for Amazon’s EC2. To find one for your region and instance
type, please refer to the
<a class="link" href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix" target="_top" shape="rect">list
of most recent AMIs</a>.
</p></li><li class="listitem"><p>
Using NixOps, the NixOS-based cloud deployment tool, which allows you to
provision VirtualBox and EC2 NixOS instances from declarative
specifications. Check out the
<a class="link" href="https://nixos.org/nixops" target="_top" shape="rect">NixOps homepage</a> for
details.
</p></li></ul></div><p>
</p></section><section class="chapter"><div class="titlepage"><div><div><h2 id="sec-installation" class="title">Chapter 2. Installing NixOS<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation" aria-label="Anchor link for: sec installation" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-booting" shape="rect">2.1. Booting the system</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning" shape="rect">2.2. Partitioning and formatting</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-installing" shape="rect">2.3. Installing</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-summary" shape="rect">2.4. Installation summary</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-additional-notes" shape="rect">2.5. Additional installation notes</a></span></dt></dl></div><section class="section"><div class="titlepage"><div><div><h2 id="sec-installation-booting" class="title" style="clear: both">2.1. Booting the system<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-booting" aria-label="Anchor link for: sec installation booting" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
NixOS can be installed on BIOS or UEFI systems. The procedure for a UEFI
installation is by and large the same as a BIOS installation. The
differences are mentioned in the steps that follow.
</p><p>
The installation media can be burned to a CD, or now more commonly, "burned"
to a USB drive (see <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb" title="2.5.1. Booting from a USB Drive" shape="rect">Section 2.5.1, “Booting from a USB Drive”</a>).
</p><p>
The installation media contains a basic NixOS installation. When it’s
finished booting, it should have detected most of your hardware.
</p><p>
The NixOS manual is available by running <span class="command"><strong>nixos-help</strong></span>.
</p><p>
You are logged-in automatically as <code class="literal">nixos</code>.
The <code class="literal">nixos</code> user account has an empty password so you
can use <span class="command"><strong>sudo</strong></span> without a password.
</p><p>
If you downloaded the graphical ISO image, you can run <span class="command"><strong>systemctl
start display-manager</strong></span> to start the desktop environment. If you want to continue on the
terminal, you can use <span class="command"><strong>loadkeys</strong></span> to switch to your
preferred keyboard layout. (We even provide neo2 via <span class="command"><strong>loadkeys de
neo</strong></span>!)
</p><p>
If the text is too small to be legible, try <span class="command"><strong>setfont ter-v32n</strong></span>
to increase the font size.
</p><section class="section"><div class="titlepage"><div><div><h3 id="sec-installation-booting-networking" class="title">2.1.1. Networking in the installer<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-booting-networking" aria-label="Anchor link for: sec installation booting networking" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
The boot process should have brought up networking (check <span class="command"><strong>ip
a</strong></span>). Networking is necessary for the installer, since it will
download lots of stuff (such as source tarballs or Nixpkgs channel
binaries). It’s best if you have a DHCP server on your network. Otherwise
configure networking manually using <span class="command"><strong>ifconfig</strong></span>.
</p><p>
To manually configure the network on the graphical installer, first disable
network-manager with <span class="command"><strong>systemctl stop NetworkManager</strong></span>.
</p><p>
To manually configure the wifi on the minimal installer, run
<span class="command"><strong>wpa_supplicant -B -i interface -c <(wpa_passphrase 'SSID'
'key')</strong></span>.
</p><p>
If you would like to continue the installation from a different machine you
can use activated SSH daemon. You need to copy your ssh key to either
<code class="literal">/home/nixos/.ssh/authorized_keys</code> or
<code class="literal">/root/.ssh/authorized_keys</code> (Tip: For installers with a
modifiable filesystem such as the sd-card installer image a key can be manually
placed by mounting the image on a different machine). Alternatively you must set
a password for either <code class="literal">root</code> or <code class="literal">nixos</code> with
<span class="command"><strong>passwd</strong></span> to be able to login.
</p></section></section><section class="section"><div class="titlepage"><div><div><h2 id="sec-installation-partitioning" class="title" style="clear: both">2.2. Partitioning and formatting<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-partitioning" aria-label="Anchor link for: sec installation partitioning" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
The NixOS installer doesn’t do any partitioning or formatting, so you need
to do that yourself.
</p><p>
The NixOS installer ships with multiple partitioning tools. The examples
below use <span class="command"><strong>parted</strong></span>, but also provides
<span class="command"><strong>fdisk</strong></span>, <span class="command"><strong>gdisk</strong></span>,
<span class="command"><strong>cfdisk</strong></span>, and <span class="command"><strong>cgdisk</strong></span>.
</p><p>
The recommended partition scheme differs depending if the computer uses
<span class="emphasis"><em>Legacy Boot</em></span> or <span class="emphasis"><em>UEFI</em></span>.
</p><section class="section"><div class="titlepage"><div><div><h3 id="sec-installation-partitioning-UEFI" class="title">2.2.1. UEFI (GPT)<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-partitioning-UEFI" aria-label="Anchor link for: sec installation partitioning UEFI" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Here's an example partition scheme for UEFI, using
<code class="filename">/dev/sda</code> as the device.
</p><div class="alert alert-info"><strong>Note:</strong>
You can safely ignore <span class="command"><strong>parted</strong></span>'s informational message
about needing to update /etc/fstab.
</div><p>
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Create a <span class="emphasis"><em>GPT</em></span> partition table.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mklabel gpt</span></span></pre><p>
</p></li><li class="listitem"><p>
Add the <span class="emphasis"><em>root</em></span> partition. This will fill the disk
except for the end part, where the swap will live, and the space left in
front (512MiB) which will be used by the boot partition.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary 512MiB -8GiB</span></span></pre><p>
</p></li><li class="listitem"><p>
Next, add a <span class="emphasis"><em>swap</em></span> partition. The size required will
vary according to needs, here a 8GiB one is created.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</span></span></pre><p>
</p><div class="alert alert-info"><strong>Note:</strong>
The swap partition size rules are no different than for other Linux
distributions.
</div><p>
</p></li><li class="listitem"><p>
Finally, the <span class="emphasis"><em>boot</em></span> partition. NixOS by default uses
the ESP (EFI system partition) as its <span class="emphasis"><em>/boot</em></span>
partition. It uses the initially reserved 512MiB at the start of the
disk.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- set 3 esp on</span></span></pre><p>
</p></li></ol></div><p>
</p><p>
Once complete, you can follow with
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning-formatting" title="2.2.3. Formatting" shape="rect">Section 2.2.3, “Formatting”</a>.
</p></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-installation-partitioning-MBR" class="title">2.2.2. Legacy Boot (MBR)<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-partitioning-MBR" aria-label="Anchor link for: sec installation partitioning MBR" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Here's an example partition scheme for Legacy Boot, using
<code class="filename">/dev/sda</code> as the device.
</p><div class="alert alert-info"><strong>Note:</strong>
You can safely ignore <span class="command"><strong>parted</strong></span>'s informational message
about needing to update /etc/fstab.
</div><p>
</p><p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Create a <span class="emphasis"><em>MBR</em></span> partition table.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mklabel msdos</span></span></pre><p>
</p></li><li class="listitem"><p>
Add the <span class="emphasis"><em>root</em></span> partition. This will fill the the disk
except for the end part, where the swap will live.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary 1MiB -8GiB</span></span></pre><p>
</p></li><li class="listitem"><p>
Finally, add a <span class="emphasis"><em>swap</em></span> partition. The size required
will vary according to needs, here a 8GiB one is created.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</span></span></pre><p>
</p><div class="alert alert-info"><strong>Note:</strong>
The swap partition size rules are no different than for other Linux
distributions.
</div><p>
</p></li></ol></div><p>
</p><p>
Once complete, you can follow with
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation-partitioning-formatting" title="2.2.3. Formatting" shape="rect">Section 2.2.3, “Formatting”</a>.
</p></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-installation-partitioning-formatting" class="title">2.2.3. Formatting<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-partitioning-formatting" aria-label="Anchor link for: sec installation partitioning formatting" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Use the following commands:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
For initialising Ext4 partitions: <span class="command"><strong>mkfs.ext4</strong></span>. It is
recommended that you assign a unique symbolic label to the file system
using the option <code class="option">-L <em class="replaceable"><code>label</code></em></code>,
since this makes the file system configuration independent from device
changes. For example:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkfs.ext4 -L nixos /dev/sda1</span></span></pre><p>
</p></li><li class="listitem"><p>
For creating swap partitions: <span class="command"><strong>mkswap</strong></span>. Again it’s
recommended to assign a label to the swap partition: <code class="option">-L
<em class="replaceable"><code>label</code></em></code>. For example:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkswap -L swap /dev/sda2</span></span></pre><p>
</p></li><li class="listitem"><div class="variablelist"><dl class="variablelist"><dt><span class="term">
UEFI systems
</span></dt><dd><p>
For creating boot partitions: <span class="command"><strong>mkfs.fat</strong></span>. Again
it’s recommended to assign a label to the boot partition:
<code class="option">-n <em class="replaceable"><code>label</code></em></code>. For example:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkfs.fat -F 32 -n boot /dev/sda3</span></span></pre><p>
</p></dd></dl></div></li><li class="listitem"><p>
For creating LVM volumes, the LVM commands, e.g.,
<span class="command"><strong>pvcreate</strong></span>, <span class="command"><strong>vgcreate</strong></span>, and
<span class="command"><strong>lvcreate</strong></span>.
</p></li><li class="listitem"><p>
For creating software RAID devices, use <span class="command"><strong>mdadm</strong></span>.
</p></li></ul></div><p>
</p></section></section><section class="section"><div class="titlepage"><div><div><h2 id="sec-installation-installing" class="title" style="clear: both">2.3. Installing<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-installing" aria-label="Anchor link for: sec installation installing" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Mount the target file system on which NixOS should be installed on
<code class="filename">/mnt</code>, e.g.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mount /dev/disk/by-label/nixos /mnt</span></span>
</pre><p>
</p></li><li class="listitem"><div class="variablelist"><dl class="variablelist"><dt><span class="term">
UEFI systems
</span></dt><dd><p>
Mount the boot file system on <code class="filename">/mnt/boot</code>, e.g.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkdir -p /mnt/boot</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mount /dev/disk/by-label/boot /mnt/boot</span></span>
</pre><p>
</p></dd></dl></div></li><li class="listitem"><p>
If your machine has a limited amount of memory, you may want to activate
swap devices now (<span class="command"><strong>swapon
<em class="replaceable"><code>device</code></em></strong></span>). The installer (or rather,
the build actions that it may spawn) may need quite a bit of RAM,
depending on your configuration.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">swapon /dev/sda2</span></span></pre><p>
</p></li><li class="listitem"><p>
You now need to create a file
<code class="filename">/mnt/etc/nixos/configuration.nix</code> that specifies the
intended configuration of the system. This is because NixOS has a
<span class="emphasis"><em>declarative</em></span> configuration model: you create or edit a
description of the desired configuration of your system, and then NixOS
takes care of making it happen. The syntax of the NixOS configuration file
is described in <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax" title="Chapter 5. Configuration Syntax" shape="rect">Chapter 5, <em>Configuration Syntax</em></a>, while a list
of available configuration options appears in
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html" title="Appendix A. Configuration Options" shape="rect">Appendix A, <em>Configuration Options</em></a>. A minimal example is shown in
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#ex-config" title="Example 2.4. NixOS Configuration" shape="rect">Example 2.4, “NixOS Configuration”</a>.
</p><p>
The command <span class="command"><strong>nixos-generate-config</strong></span> can generate an
initial configuration file for you:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-generate-config --root /mnt</span></span></pre><p>
You should then edit <code class="filename">/mnt/etc/nixos/configuration.nix</code>
to suit your needs:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nano /mnt/etc/nixos/configuration.nix</span></span>
</pre><p>
If you’re using the graphical ISO image, other editors may be available
(such as <span class="command"><strong>vim</strong></span>). If you have network access, you can also
install other editors — for instance, you can install Emacs by running
<code class="literal">nix-env -f '<nixpkgs>' -iA emacs</code>.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
BIOS systems
</span></dt><dd><p>
You <span class="emphasis"><em>must</em></span> set the option
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.grub.device" shape="rect"><code class="option">boot.loader.grub.device</code></a> to specify on which disk
the GRUB boot loader is to be installed. Without it, NixOS cannot boot.
</p></dd><dt><span class="term">
UEFI systems
</span></dt><dd><p>
You <span class="emphasis"><em>must</em></span> set the option
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.systemd-boot.enable" shape="rect"><code class="option">boot.loader.systemd-boot.enable</code></a> to
<code class="literal">true</code>. <span class="command"><strong>nixos-generate-config</strong></span>
should do this automatically for new configurations when booted in UEFI
mode.
</p><p>
You may want to look at the options starting with
<code class="option"><a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.efi.canTouchEfiVariables" shape="rect">boot.loader.efi</a></code>
and
<code class="option"><a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.systemd-boot.enable" shape="rect">boot.loader.systemd</a></code>
as well.
</p></dd></dl></div><p>
If there are other operating systems running on the machine before
installing NixOS, the <a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.grub.useOSProber" shape="rect"><code class="option">boot.loader.grub.useOSProber</code></a>
option can be set to <code class="literal">true</code> to automatically add them to
the grub menu.
</p><p>
If you need to configure networking for your machine the configuration
options are described in <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-networking" title="Chapter 12. Networking" shape="rect">Chapter 12, <em>Networking</em></a>. In particular,
while wifi is supported on the installation image, it is not enabled by
default in the configuration generated by
<span class="command"><strong>nixos-generate-config</strong></span>.
</p><p>
Another critical option is <code class="option">fileSystems</code>, specifying the
file systems that need to be mounted by NixOS. However, you typically
don’t need to set it yourself, because
<span class="command"><strong>nixos-generate-config</strong></span> sets it automatically in
<code class="filename">/mnt/etc/nixos/hardware-configuration.nix</code> from your
currently mounted file systems. (The configuration file
<code class="filename">hardware-configuration.nix</code> is included from
<code class="filename">configuration.nix</code> and will be overwritten by future
invocations of <span class="command"><strong>nixos-generate-config</strong></span>; thus, you
generally should not modify it.) Additionally, you may want to look at
<a class="link" href="https://github.com/NixOS/nixos-hardware" target="_top" shape="rect">Hardware
configuration for known-hardware</a> at this point or after
installation.
</p><div class="alert alert-info"><strong>Note:</strong>
Depending on your hardware configuration or type of file system, you may
need to set the option <code class="option">boot.initrd.kernelModules</code> to
include the kernel modules that are necessary for mounting the root file
system, otherwise the installed system will not be able to boot. (If this
happens, boot from the installation media again, mount the target file
system on <code class="filename">/mnt</code>, fix
<code class="filename">/mnt/etc/nixos/configuration.nix</code> and rerun
<code class="filename">nixos-install</code>.) In most cases,
<span class="command"><strong>nixos-generate-config</strong></span> will figure out the required
modules.
</div></li><li class="listitem"><p>
Do the installation:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-install</span></span></pre><p>
This will install your system based on the configuration you provided.
If anything fails due to a configuration problem or any other issue
(such as a network outage while downloading binaries from the NixOS
binary cache), you can re-run <span class="command"><strong>nixos-install</strong></span> after
fixing your <code class="filename">configuration.nix</code>.
</p><p>
As the last step, <span class="command"><strong>nixos-install</strong></span> will ask you to set the
password for the <code class="literal">root</code> user, e.g.
</p><pre class="screen hljs" xml:space="preserve">setting root password...
Enter new UNIX password: ***
Retype new UNIX password: ***</pre><p>
</p><div class="alert alert-info"><strong>Note:</strong>
For unattended installations, it is possible to use
<span class="command"><strong>nixos-install --no-root-passwd</strong></span> in order to disable
the password prompt entirely.
</div><p>
</p></li><li class="listitem"><p>
If everything went well:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">reboot</span></span></pre><p>
</p></li><li class="listitem"><p>
You should now be able to boot into the installed NixOS. The GRUB boot
menu shows a list of <span class="emphasis"><em>available configurations</em></span>
(initially just one). Every time you change the NixOS configuration (see
<a class="link" href="https://nixos.org/manual/nixos/stable/index.html#sec-changing-config" title="Chapter 3. Changing the Configuration" shape="rect">Changing Configuration</a>
), a new item is added to the menu. This allows you to easily roll back to
a previous configuration if something goes wrong.
</p><p>
You should log in and change the <code class="literal">root</code> password with
<span class="command"><strong>passwd</strong></span>.
</p><p>
You’ll probably want to create some user accounts as well, which can be
done with <span class="command"><strong>useradd</strong></span>:
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>useradd -c <span class="hljs-string"><span class="hljs-string">'Eelco Dolstra'</span></span> -m eelco
<code class="prompt">$ </code>passwd eelco</pre><p>
</p><p>
You may also want to install some software. For instance,
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>nix-env -qaP \*</pre><p>
shows what packages are available, and
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>nix-env -f <span class="hljs-string"><span class="hljs-string">'<nixpkgs>'</span></span> -iA w3m</pre><p>
installs the <code class="literal">w3m</code> browser.
</p></li></ol></div></section><section class="section"><div class="titlepage"><div><div><h2 id="sec-installation-summary" class="title" style="clear: both">2.4. Installation summary<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-summary" aria-label="Anchor link for: sec installation summary" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
To summarise, <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#ex-install-sequence" title="Example 2.3. Commands for Installing NixOS on /dev/sda" shape="rect">Example 2.3, “Commands for Installing NixOS on <code class="filename">/dev/sda</code>”</a> shows a typical
sequence of commands for installing NixOS on an empty hard drive (here
<code class="filename">/dev/sda</code>). <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#ex-config" title="Example 2.4. NixOS Configuration" shape="rect">Example 2.4, “NixOS Configuration”</a> shows a
corresponding configuration Nix expression.
</p><div class="example"><a id="ex-partition-scheme-MBR" shape="rect"></a><p class="title"><strong>Example 2.1. Example partition schemes for NixOS on <code class="filename">/dev/sda</code> (MBR)</strong></p><div class="example-contents"><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mklabel msdos</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary 1MiB -8GiB</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</span></span></pre></div></div><br class="example-break" clear="none"><br><div class="example"><a id="ex-partition-scheme-UEFI" shape="rect"></a><p class="title"><strong>Example 2.2. Example partition schemes for NixOS on <code class="filename">/dev/sda</code> (UEFI)</strong></p><div class="example-contents"><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mklabel gpt</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary 512MiB -8GiB</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">parted /dev/sda -- set 3 esp on</span></span></pre></div></div><br class="example-break" clear="none"><br><div class="example"><a id="ex-install-sequence" shape="rect"></a><p class="title"><strong>Example 2.3. Commands for Installing NixOS on <code class="filename">/dev/sda</code></strong></p><div class="example-contents"><p>
With a partitioned disk.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkfs.ext4 -L nixos /dev/sda1</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkswap -L swap /dev/sda2</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">swapon /dev/sda2</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkfs.fat -F 32 -n boot /dev/sda3 # </span></span><em class="lineannotation"><span class="lineannotation"><span class="hljs-comment"><span class="hljs-comment">(for UEFI systems only)</span></span></span></em>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mount /dev/disk/by-label/nixos /mnt</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkdir -p /mnt/boot # </span></span><em class="lineannotation"><span class="lineannotation"><span class="hljs-comment"><span class="hljs-comment">(for UEFI systems only)</span></span></span></em>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mount /dev/disk/by-label/boot /mnt/boot # </span></span><em class="lineannotation"><span class="lineannotation"><span class="hljs-comment"><span class="hljs-comment">(for UEFI systems only)</span></span></span></em>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-generate-config --root /mnt</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nano /mnt/etc/nixos/configuration.nix</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-install</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">reboot</span></span></pre><p>
</p></div></div><br class="example-break" clear="none"><br><div class="example"><a id="ex-config" shape="rect"></a><p class="title"><strong>Example 2.4. NixOS Configuration</strong></p><div class="example-contents"><pre class="programlisting hljs nix" xml:space="preserve">{ config, pkgs, ... }: {
<span class="hljs-attr"><span class="hljs-attr">imports</span></span> = [
<span class="hljs-comment"><span class="hljs-comment"># Include the results of the hardware scan.</span></span>
./hardware-configuration.nix
];
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.grub.device" shape="rect"><code class="option">boot.loader.grub.<span class="hljs-attr"><span class="hljs-attr">device</span></span></code></a> = <span class="hljs-string"><span class="hljs-string">"/dev/sda"</span></span>; <span class="hljs-comment"><span class="hljs-comment"># </span></span><em class="lineannotation"><span class="lineannotation"><span class="hljs-comment"><span class="hljs-comment">(for BIOS systems only)</span></span></span></em>
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.systemd-boot.enable" shape="rect"><code class="option">boot.loader.systemd-boot.<span class="hljs-attr"><span class="hljs-attr">enable</span></span></code></a> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>; <span class="hljs-comment"><span class="hljs-comment"># </span></span><em class="lineannotation"><span class="lineannotation"><span class="hljs-comment"><span class="hljs-comment">(for UEFI systems only)</span></span></span></em>
<span class="hljs-comment"><span class="hljs-comment"># Note: setting fileSystems is generally not</span></span>
<span class="hljs-comment"><span class="hljs-comment"># necessary, since nixos-generate-config figures them out</span></span>
<span class="hljs-comment"><span class="hljs-comment"># automatically in hardware-configuration.nix.</span></span>
<span class="hljs-comment"><span class="hljs-comment">#</span></span><a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-fileSystems._name_.device" shape="rect"><span class="hljs-comment"><span class="hljs-comment">fileSystems."/".device</span></span></a><span class="hljs-comment"><span class="hljs-comment"> = "/dev/disk/by-label/nixos";</span></span>
<span class="hljs-comment"><span class="hljs-comment"># Enable the OpenSSH server.</span></span>
services.sshd.<span class="hljs-attr"><span class="hljs-attr">enable</span></span> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>;
}
</pre></div></div><br class="example-break" clear="none"><br></section><section class="section"><div class="titlepage"><div><div><h2 id="sec-installation-additional-notes" class="title" style="clear: both">2.5. Additional installation notes<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installation-additional-notes" aria-label="Anchor link for: sec installation additional notes" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><section class="section"><div class="titlepage"><div><div><h3 id="sec-booting-from-usb" class="title">2.5.1. Booting from a USB Drive<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-booting-from-usb" aria-label="Anchor link for: sec booting from usb" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
For systems without CD drive, the NixOS live CD can be booted from a USB
stick. You can use the <span class="command"><strong>dd</strong></span> utility to write the image:
<span class="command"><strong>dd if=<em class="replaceable"><code>path-to-image</code></em>
of=<em class="replaceable"><code>/dev/sdX</code></em></strong></span>. Be careful about specifying
the correct drive; you can use the <span class="command"><strong>lsblk</strong></span> command to get a
list of block devices.
</p><div class="note"><h3 class="title" id="on-macos">On macOS<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#on-macos" aria-label="Anchor link for: on macos" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3><p>
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt">$ </code>diskutil list
[..]
/dev/diskN (external, physical):
<span class="hljs-comment"><span class="hljs-comment">#: TYPE NAME SIZE IDENTIFIER</span></span>
[..]
<code class="prompt">$ </code>diskutil unmountDisk diskN
Unmount of all volumes on diskN was successful
<code class="prompt">$ </code>sudo dd <span class="hljs-attr"><span class="hljs-attr">if=nix.iso</span></span> <span class="hljs-attr"><span class="hljs-attr">of=/dev/rdiskN</span></span>
</pre><p>
Using the 'raw' <span class="command"><strong>rdiskN</strong></span> device instead of
<span class="command"><strong>diskN</strong></span> completes in minutes instead of hours. After
<span class="command"><strong>dd</strong></span> completes, a GUI dialog "The disk you inserted was
not readable by this computer" will pop up, which can be ignored.
</p></div><p>
</p><p>
The <span class="command"><strong>dd</strong></span> utility will write the image verbatim to the drive,
making it the recommended option for both UEFI and non-UEFI installations.
</p></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-booting-from-pxe" class="title">2.5.2. Booting from the <span class="quote">“<span class="quote">netboot</span>”</span> media (PXE)<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-booting-from-pxe" aria-label="Anchor link for: sec booting from pxe" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Advanced users may wish to install NixOS using an existing PXE or iPXE setup.
</p><p>
These instructions assume that you have an existing PXE or iPXE
infrastructure and simply want to add the NixOS installer as another option.
To build the necessary files from a recent version of nixpkgs, you can run:
</p><pre class="programlisting hljs" xml:space="preserve">nix-build -A netboot.x86_64-linux nixos/release.nix
</pre><p>
This will create a <code class="literal">result</code> directory containing: *
<code class="literal">bzImage</code> – the Linux kernel * <code class="literal">initrd</code>
– the initrd file * <code class="literal">netboot.ipxe</code> – an example ipxe
script demonstrating the appropriate kernel command line arguments for this
image
</p><p>
If you’re using plain PXE, configure your boot loader to use the
<code class="literal">bzImage</code> and <code class="literal">initrd</code> files and have it
provide the same kernel command line arguments found in
<code class="literal">netboot.ipxe</code>.
</p><p>
If you’re using iPXE, depending on how your HTTP/FTP/etc. server is
configured you may be able to use <code class="literal">netboot.ipxe</code> unmodified,
or you may need to update the paths to the files to match your server’s
directory layout
</p><p>
In the future we may begin making these files available as build products
from hydra at which point we will update this documentation with instructions
on how to obtain them either for placing on a dedicated TFTP server or to
boot them directly over the internet.
</p></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-instaling-virtualbox-guest" class="title">2.5.3. Installing in a VirtualBox guest<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-instaling-virtualbox-guest" aria-label="Anchor link for: sec instaling virtualbox guest" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Installing NixOS into a VirtualBox guest is convenient for users who want to
try NixOS without installing it on bare metal. If you want to use a pre-made
VirtualBox appliance, it is available at
<a class="link" href="https://nixos.org/nixos/download.html" target="_top" shape="rect">the downloads
page</a>. If you want to set up a VirtualBox guest manually, follow these
instructions:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Add a New Machine in VirtualBox with OS Type "Linux / Other Linux"
</p></li><li class="listitem"><p>
Base Memory Size: 768 MB or higher.
</p></li><li class="listitem"><p>
New Hard Disk of 8 GB or higher.
</p></li><li class="listitem"><p>
Mount the CD-ROM with the NixOS ISO (by clicking on CD/DVD-ROM)
</p></li><li class="listitem"><p>
Click on Settings / System / Processor and enable PAE/NX
</p></li><li class="listitem"><p>
Click on Settings / System / Acceleration and enable "VT-x/AMD-V"
acceleration
</p></li><li class="listitem"><p>
Click on Settings / Display / Screen and select VMSVGA as Graphics Controller
</p></li><li class="listitem"><p>
Save the settings, start the virtual machine, and continue installation
like normal
</p></li></ol></div><p>
There are a few modifications you should make in configuration.nix. Enable
booting:
</p><pre class="programlisting hljs nix" xml:space="preserve"><a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.grub.device" shape="rect"><code class="option">boot.loader.grub.<span class="hljs-attr"><span class="hljs-attr">device</span></span></code></a> = <span class="hljs-string"><span class="hljs-string">"/dev/sda"</span></span>;
</pre><p>
Also remove the fsck that runs at startup. It will always fail to run,
stopping your boot until you press <code class="literal">*</code>.
</p><pre class="programlisting hljs nix" xml:space="preserve"><a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.initrd.checkJournalingFS" shape="rect"><code class="option">boot.initrd.<span class="hljs-attr"><span class="hljs-attr">checkJournalingFS</span></span></code></a> = <span class="hljs-literal"><span class="hljs-literal">false</span></span>;
</pre><p>
Shared folders can be given a name and a path in the host system in the
VirtualBox settings (Machine / Settings / Shared Folders, then click on the
"Add" icon). Add the following to the
<code class="literal">/etc/nixos/configuration.nix</code> to auto-mount them. If you do
not add <code class="literal">"nofail"</code>, the system will no boot properly. The
same goes for disabling <code class="literal">rngd</code> which is normally used to get
randomness but this does not work in virtual machines.
</p><pre class="programlisting hljs nix" xml:space="preserve">{ config, pkgs, ...} :
{
security.rngd.<span class="hljs-attr"><span class="hljs-attr">enable</span></span> = <span class="hljs-literal"><span class="hljs-literal">false</span></span>; // otherwise vm will not boot
...
fileSystems.<span class="hljs-string"><span class="hljs-string">"/virtualboxshare"</span></span> = {
<span class="hljs-attr"><span class="hljs-attr">fsType</span></span> = <span class="hljs-string"><span class="hljs-string">"vboxsf"</span></span>;
<span class="hljs-attr"><span class="hljs-attr">device</span></span> = <span class="hljs-string"><span class="hljs-string">"nameofthesharedfolder"</span></span>;
<span class="hljs-attr"><span class="hljs-attr">options</span></span> = [ <span class="hljs-string"><span class="hljs-string">"rw"</span></span> <span class="hljs-string"><span class="hljs-string">"nofail"</span></span> ];
};
}
</pre><p>
The folder will be available directly under the root directory.
</p></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-installing-from-other-distro" class="title">2.5.4. Installing from another Linux distribution<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installing-from-other-distro" aria-label="Anchor link for: sec installing from other distro" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
Because Nix (the package manager) & Nixpkgs (the Nix packages collection)
can both be installed on any (most?) Linux distributions, they can be used to
install NixOS in various creative ways. You can, for instance:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Install NixOS on another partition, from your existing Linux distribution
(without the use of a USB or optical device!)
</p></li><li class="listitem"><p>
Install NixOS on the same partition (in place!), from your existing
non-NixOS Linux distribution using <code class="literal">NIXOS_LUSTRATE</code>.
</p></li><li class="listitem"><p>
Install NixOS on your hard drive from the Live CD of any Linux
distribution.
</p></li></ol></div><p>
The first steps to all these are the same:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Install the Nix package manager:
</p><p>
Short version:
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>curl -L https://nixos.org/nix/install | sh
<code class="prompt">$ </code>. <span class="hljs-variable"><span class="hljs-variable">$HOME</span></span>/.nix-profile/etc/profile.d/nix.sh <span class="hljs-comment"><span class="hljs-comment"># …or open a fresh shell</span></span></pre><p>
More details in the
<a class="link" href="https://nixos.org/nix/manual/#chap-quick-start" target="_top" shape="rect">
Nix manual</a>
</p></li><li class="listitem"><p>
Switch to the NixOS channel:
</p><p>
If you've just installed Nix on a non-NixOS distribution, you will be on
the <code class="literal">nixpkgs</code> channel by default.
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>nix-channel --list
nixpkgs https://nixos.org/channels/nixpkgs-unstable</pre><p>
As that channel gets released without running the NixOS tests, it will be
safer to use the <code class="literal">nixos-*</code> channels instead:
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>nix-channel --add https://nixos.org/channels/nixos-<em class="replaceable"><code>version</code></em> nixpkgs</pre><p>
You may want to throw in a <code class="literal">nix-channel --update</code> for good
measure.
</p></li><li class="listitem"><p>
Install the NixOS installation tools:
</p><p>
You'll need <code class="literal">nixos-generate-config</code> and
<code class="literal">nixos-install</code> and we'll throw in some man pages and
<code class="literal">nixos-enter</code> just in case you want to chroot into your
NixOS partition. They are installed by default on NixOS, but you don't have
NixOS yet..
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>nix-env -f <span class="hljs-string"><span class="hljs-string">'<nixpkgs/nixos>'</span></span> --arg configuration {} -iA config.system.build.{nixos-generate-config,nixos-install,nixos-enter,manual.manpages}</pre></li><li class="listitem"><div class="alert alert-info"><strong>Note:</strong>
The following 5 steps are only for installing NixOS to another partition.
For installing NixOS in place using <code class="literal">NIXOS_LUSTRATE</code>,
skip ahead.
</div><p>
Prepare your target partition:
</p><p>
At this point it is time to prepare your target partition. Please refer to
the partitioning, file-system creation, and mounting steps of
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" title="Chapter 2. Installing NixOS" shape="rect">Chapter 2, <em>Installing NixOS</em></a>
</p><p>
If you're about to install NixOS in place using
<code class="literal">NIXOS_LUSTRATE</code> there is nothing to do for this step.
</p></li><li class="listitem"><p>
Generate your NixOS configuration:
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>sudo `<span class="hljs-built_in"><span class="hljs-built_in">which</span></span> nixos-generate-config` --root /mnt</pre><p>
You'll probably want to edit the configuration files. Refer to the
<code class="literal">nixos-generate-config</code> step in
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" title="Chapter 2. Installing NixOS" shape="rect">Chapter 2, <em>Installing NixOS</em></a> for more
information.
</p><p>
Consider setting up the NixOS bootloader to give you the ability to boot on
your existing Linux partition. For instance, if you're using GRUB and your
existing distribution is running Ubuntu, you may want to add something like
this to your <code class="literal">configuration.nix</code>:
</p><pre class="programlisting hljs bash" xml:space="preserve"><a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-boot.loader.grub.extraEntries" shape="rect"><code class="option">boot.loader.grub.extraEntries</code></a> = <span class="hljs-string"><span class="hljs-string">''</span></span>
menuentry <span class="hljs-string"><span class="hljs-string">"Ubuntu"</span></span> {
search --<span class="hljs-built_in"><span class="hljs-built_in">set</span></span>=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
configfile <span class="hljs-string"><span class="hljs-string">"(</span><span class="hljs-variable"><span class="hljs-string"><span class="hljs-variable">$ubuntu</span></span></span><span class="hljs-string">)/boot/grub/grub.cfg"</span></span>
}
<span class="hljs-string"><span class="hljs-string">''</span></span>;</pre><p>
(You can find the appropriate UUID for your partition in
<code class="literal">/dev/disk/by-uuid</code>)
</p></li><li class="listitem"><p>
Create the <code class="literal">nixbld</code> group and user on your original
distribution:
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>sudo groupadd -g 30000 nixbld
<code class="prompt">$ </code>sudo useradd -u 30000 -g nixbld -G nixbld nixbld</pre></li><li class="listitem"><p>
Download/build/install NixOS:
</p><div class="alert alert-warning"><strong>Warning:</strong>
Once you complete this step, you might no longer be able to boot on
existing systems without the help of a rescue USB drive or similar.
</div><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>sudo PATH=<span class="hljs-string"><span class="hljs-string">"</span><span class="hljs-variable"><span class="hljs-string"><span class="hljs-variable">$PATH</span></span></span><span class="hljs-string">"</span></span> NIX_PATH=<span class="hljs-string"><span class="hljs-string">"</span><span class="hljs-variable"><span class="hljs-string"><span class="hljs-variable">$NIX_PATH</span></span></span><span class="hljs-string">"</span></span> `<span class="hljs-built_in"><span class="hljs-built_in">which</span></span> nixos-install` --root /mnt</pre><p>
Again, please refer to the <code class="literal">nixos-install</code> step in
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" title="Chapter 2. Installing NixOS" shape="rect">Chapter 2, <em>Installing NixOS</em></a> for more information.
</p><p>
That should be it for installation to another partition!
</p></li><li class="listitem"><p>
Optionally, you may want to clean up your non-NixOS distribution:
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>sudo userdel nixbld
<code class="prompt">$ </code>sudo groupdel nixbld</pre><p>
If you do not wish to keep the Nix package manager installed either, run
something like <code class="literal">sudo rm -rv ~/.nix-* /nix</code> and remove the
line that the Nix installer added to your <code class="literal">~/.profile</code>.
</p></li><li class="listitem"><div class="alert alert-info"><strong>Note:</strong>
The following steps are only for installing NixOS in place using
<code class="literal">NIXOS_LUSTRATE</code>:
</div><p>
Generate your NixOS configuration:
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code>sudo `<span class="hljs-built_in"><span class="hljs-built_in">which</span></span> nixos-generate-config` --root /</pre><p>
Note that this will place the generated configuration files in
<code class="literal">/etc/nixos</code>. You'll probably want to edit the
configuration files. Refer to the <code class="literal">nixos-generate-config</code>
step in <a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-installation" title="Chapter 2. Installing NixOS" shape="rect">Chapter 2, <em>Installing NixOS</em></a> for more
information.
</p><p>
You'll likely want to set a root password for your first boot using the
configuration files because you won't have a chance to enter a password
until after you reboot. You can initalize the root password to an empty one
with this line: (and of course don't forget to set one once you've rebooted
or to lock the account with <code class="literal">sudo passwd -l root</code> if you
use <code class="literal">sudo</code>)
</p><pre class="programlisting hljs nix" xml:space="preserve"><a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-users.users._name_.initialHashedPassword" shape="rect">users.users.root.<span class="hljs-attr"><span class="hljs-attr">initialHashedPassword</span></span></a> = <span class="hljs-string"><span class="hljs-string">""</span></span>;
</pre></li><li class="listitem"><p>
Build the NixOS closure and install it in the <code class="literal">system</code>
profile:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt">$ </code>nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I <span class="hljs-attr"><span class="hljs-attr">nixos-config=/etc/nixos/configuration.nix</span></span> -iA system</pre></li><li class="listitem"><p>
Change ownership of the <code class="literal">/nix</code> tree to root (since your
Nix install was probably single user):
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>sudo chown -R 0.0 /nix</pre></li><li class="listitem"><p>
Set up the <code class="literal">/etc/NIXOS</code> and
<code class="literal">/etc/NIXOS_LUSTRATE</code> files:
</p><p>
<code class="literal">/etc/NIXOS</code> officializes that this is now a NixOS
partition (the bootup scripts require its presence).
</p><p>
<code class="literal">/etc/NIXOS_LUSTRATE</code> tells the NixOS bootup scripts to
move <span class="emphasis"><em>everything</em></span> that's in the root partition to
<code class="literal">/old-root</code>. This will move your existing distribution out
of the way in the very early stages of the NixOS bootup. There are
exceptions (we do need to keep NixOS there after all), so the NixOS
lustrate process will not touch:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The <code class="literal">/nix</code> directory
</p></li><li class="listitem"><p>
The <code class="literal">/boot</code> directory
</p></li><li class="listitem"><p>
Any file or directory listed in <code class="literal">/etc/NIXOS_LUSTRATE</code>
(one per line)
</p></li></ul></div><div class="note"><h3 class="title" id="note">Note<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#note" aria-label="Anchor link for: note" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3><p>
Support for <code class="literal">NIXOS_LUSTRATE</code> was added in NixOS 16.09.
The act of "lustrating" refers to the wiping of the existing distribution.
Creating <code class="literal">/etc/NIXOS_LUSTRATE</code> can also be used on NixOS
to remove all mutable files from your root partition (anything that's not
in <code class="literal">/nix</code> or <code class="literal">/boot</code> gets "lustrated" on
the next boot.
</p><p>
lustrate /ˈlʌstreɪt/ verb.
</p><p>
purify by expiatory sacrifice, ceremonial washing, or some other ritual
action.
</p></div><p>
Let's create the files:
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>sudo touch /etc/NIXOS
<code class="prompt">$ </code>sudo touch /etc/NIXOS_LUSTRATE
</pre><p>
Let's also make sure the NixOS configuration files are kept once we reboot
on NixOS:
</p><pre class="screen hljs bash" xml:space="preserve"><code class="prompt">$ </code><span class="hljs-built_in"><span class="hljs-built_in">echo</span></span> etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
</pre></li><li class="listitem"><p>
Finally, move the <code class="literal">/boot</code> directory of your current
distribution out of the way (the lustrate process will take care of the
rest once you reboot, but this one must be moved out now because NixOS
needs to install its own boot files:
</p><div class="alert alert-warning"><strong>Warning:</strong>
Once you complete this step, your current distribution will no longer be
bootable! 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. Have a USB rescue device ready in case this
happens.
</div><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>sudo mv -v /boot /boot.bak &&
sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot
</pre><p>
Cross your fingers, reboot, hopefully you should get a NixOS prompt!
</p></li><li class="listitem"><p>
If for some reason you want to revert to the old distribution, you'll need
to boot on a USB rescue disk and do something along these lines:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkdir root</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mount /dev/sdaX root</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mkdir root/nixos-root</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mv -v root/* root/nixos-root/</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mv -v root/nixos-root/old-root/* root/</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">mv -v root/boot.bak root/boot # We had renamed this by hand earlier</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">umount root</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">reboot</span></span></pre><p>
This may work as is or you might also need to reinstall the boot loader
</p><p>
And of course, if you're happy with NixOS and no longer need the old
distribution:
</p><pre class="screen hljs" xml:space="preserve">sudo rm -rf /old-root</pre></li><li class="listitem"><p>
It's also worth noting that this whole process can be automated. This is
especially useful for Cloud VMs, where provider do not provide NixOS. For
instance,
<a class="link" href="https://github.com/elitak/nixos-infect" target="_top" shape="rect">nixos-infect</a>
uses the lustrate process to convert Digital Ocean droplets to NixOS from
other distributions automatically.
</p></li></ol></div></section><section class="section"><div class="titlepage"><div><div><h3 id="sec-installing-behind-proxy" class="title">2.5.5. Installing behind a proxy<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-installing-behind-proxy" aria-label="Anchor link for: sec installing behind proxy" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h3></div></div></div><p>
To install NixOS behind a proxy, do the following before running
<code class="literal">nixos-install</code>.
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Update proxy configuration in
<code class="literal">/mnt/etc/nixos/configuration.nix</code> to keep the internet
accessible after reboot.
</p><pre class="programlisting hljs nix" xml:space="preserve">networking.proxy.<span class="hljs-attr"><span class="hljs-attr">default</span></span> = <span class="hljs-string"><span class="hljs-string">"http://user:password@proxy:port/"</span></span>;
networking.proxy.<span class="hljs-attr"><span class="hljs-attr">noProxy</span></span> = <span class="hljs-string"><span class="hljs-string">"127.0.0.1,localhost,internal.domain"</span></span>;
</pre></li><li class="listitem"><p>
Setup the proxy environment variables in the shell where you are running
<code class="literal">nixos-install</code>.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">proxy_url="http://user:password@proxy:port/"</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">export http_proxy="$proxy_url"</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">export HTTP_PROXY="$proxy_url"</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">export https_proxy="$proxy_url"</span></span>
<code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">export HTTPS_PROXY="$proxy_url"</span></span>
</pre></li></ol></div><div class="alert alert-info"><strong>Note:</strong>
If you are switching networks with different proxy configurations, use the
<code class="literal">specialisation</code> option in
<code class="literal">configuration.nix</code> to switch proxies at runtime. Refer to
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html" title="Appendix A. Configuration Options" shape="rect">Appendix A, <em>Configuration Options</em></a> for more information.
</div></section></section></section><section class="chapter"><div class="titlepage"><div><div><h2 id="sec-changing-config" class="title">Chapter 3. Changing the Configuration<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-changing-config" aria-label="Anchor link for: sec changing config" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
The file <code class="filename">/etc/nixos/configuration.nix</code> contains the
current configuration of your machine. Whenever you’ve
<a class="link" href="https://nixos.org/manual/nixos/stable/index.html#ch-configuration" title="Part II. Configuration" shape="rect">changed something</a> in that file, you
should do
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-rebuild switch</span></span>
</pre><p>
to build the new configuration, make it the default configuration for
booting, and try to realise the configuration in the running system (e.g., by
restarting system services).
</p><div class="alert alert-warning"><strong>Warning:</strong>
This command doesn't start/stop <a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-systemd.user.services" shape="rect">user
services</a> automatically. <span class="command"><strong>nixos-rebuild</strong></span> only runs a
<code class="literal">daemon-reload</code> for each user with running user services.
</div><p>
</p><div class="alert alert-warning"><strong>Warning:</strong>
These commands must be executed as root, so you should either run them from
a root shell or by prefixing them with <code class="literal">sudo -i</code>.
</div><p>
You can also do
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-rebuild test</span></span>
</pre><p>
to build the configuration and switch the running system to it, but without
making it the boot default. So if (say) the configuration locks up your
machine, you can just reboot to get back to a working configuration.
</p><p>
There is also
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-rebuild boot</span></span>
</pre><p>
to build the configuration and make it the boot default, but not switch to it
now (so it will only take effect after the next reboot).
</p><p>
You can make your configuration show up in a different submenu of the GRUB 2
boot screen by giving it a different <span class="emphasis"><em>profile name</em></span>, e.g.
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-rebuild switch -p test</span></span>
</pre><p>
which causes the new configuration (and previous ones created using
<code class="literal">-p test</code>) to show up in the GRUB submenu “NixOS - Profile
'test'”. This can be useful to separate test configurations from
“stable” configurations.
</p><p>
Finally, you can do
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>nixos-rebuild build
</pre><p>
to build the configuration but nothing more. This is useful to see whether
everything compiles cleanly.
</p><p>
If you have a machine that supports hardware virtualisation, you can also
test the new configuration in a sandbox by building and running a QEMU
<span class="emphasis"><em>virtual machine</em></span> that contains the desired configuration.
Just do
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>nixos-rebuild build-vm
<code class="prompt">$ </code>./result/bin/run-*-vm
</pre><p>
The VM does not have any data from your host system, so your existing user
accounts and home directories will not be available unless you have set
<code class="literal">mutableUsers = false</code>. Another way is to temporarily add
the following to your configuration:
</p><pre class="screen hljs nix" xml:space="preserve"><a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-users.users._name_.initialHashedPassword" shape="rect">users.users.your-user.<span class="hljs-attr"><span class="hljs-attr">initialHashedPassword</span></span></a> = <span class="hljs-string"><span class="hljs-string">"test"</span></span>;
</pre><p>
<span class="emphasis"><em>Important:</em></span> delete the $hostname.qcow2 file if you have
started the virtual machine at least once without the right users, otherwise
the changes will not get picked up. You can forward ports on the host to the
guest. For instance, the following will forward host port 2222 to guest port
22 (SSH):
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt">$ </code><span class="hljs-attr"><span class="hljs-attr">QEMU_NET_OPTS="hostfwd=tcp::2222-:22"</span></span> ./result/bin/run-*-vm
</pre><p>
allowing you to log in via SSH (assuming you have set the appropriate
passwords or SSH authorized keys):
</p><pre class="screen hljs" xml:space="preserve"><code class="prompt">$ </code>ssh -p 2222 localhost
</pre><p>
</p></section><section class="chapter"><div class="titlepage"><div><div><h2 id="sec-upgrading" class="title">Chapter 4. Upgrading NixOS<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-upgrading" aria-label="Anchor link for: sec upgrading" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-upgrading-automatic" shape="rect">4.1. Automatic Upgrades</a></span></dt></dl></div><p>
The best way to keep your NixOS installation up to date is to use one of the
NixOS <span class="emphasis"><em>channels</em></span>. A channel is a Nix mechanism for
distributing Nix expressions and associated binaries. The NixOS channels are
updated automatically from NixOS’s Git repository after certain tests have
passed and all packages have been built. These channels are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>Stable channels</em></span>, such as
<code class="literal"><a class="literal" href="https://nixos.org/channels/nixos-20.09" target="_top" shape="rect">nixos-20.09</a></code>.
These only get conservative bug fixes and package upgrades. For instance,
a channel update may cause the Linux kernel on your system to be upgraded
from 4.19.34 to 4.19.38 (a minor bug fix), but not from
4.19.<em class="replaceable"><code>x</code></em> to 4.20.<em class="replaceable"><code>x</code></em> (a
major change that has the potential to break things). Stable channels are
generally maintained until the next stable branch is created.
</p><p></p></li><li class="listitem"><p>
The <span class="emphasis"><em>unstable channel</em></span>,
<code class="literal"><a class="literal" href="https://nixos.org/channels/nixos-unstable" target="_top" shape="rect">nixos-unstable</a></code>.
This corresponds to NixOS’s main development branch, and may thus see
radical changes between channel updates. It’s not recommended for
production systems.
</p></li><li class="listitem"><p>
<span class="emphasis"><em>Small channels</em></span>, such as
<code class="literal"><a class="literal" href="https://nixos.org/channels/nixos-20.09-small" target="_top" shape="rect">nixos-20.09-small</a></code>
or
<code class="literal"><a class="literal" href="https://nixos.org/channels/nixos-unstable-small" target="_top" shape="rect">nixos-unstable-small</a></code>.
These are identical to the stable and unstable channels described above,
except that they contain fewer binary packages. This means they get
updated faster than the regular channels (for instance, when a critical
security patch is committed to NixOS’s source tree), but may require
more packages to be built from source than usual. They’re mostly
intended for server environments and as such contain few GUI applications.
</p></li></ul></div><p>
To see what channels are available, go to
<a class="link" href="https://nixos.org/channels" target="_top" shape="rect">https://nixos.org/channels</a>. (Note that the URIs of the
various channels redirect to a directory that contains the channel’s latest
version and includes ISO images and VirtualBox appliances.) Please note that
during the release process, channels that are not yet released will be
present here as well. See the Getting NixOS page
<a class="link" href="https://nixos.org/nixos/download.html" target="_top" shape="rect">https://nixos.org/nixos/download.html</a> to find the newest
supported stable release.
</p><p>
When you first install NixOS, you’re automatically subscribed to the NixOS
channel that corresponds to your installation source. For instance, if you
installed from a 20.09 ISO, you will be subscribed to the
<code class="literal">nixos-20.09</code> channel. To see which NixOS channel you’re
subscribed to, run the following as root:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nix-channel --list | grep nixos</span></span>
nixos https://nixos.org/channels/nixos-unstable
</pre><p>
To switch to a different NixOS channel, do
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nix-channel --add https://nixos.org/channels/</span></span><em class="replaceable"><code><span class="hljs-comment"><span class="hljs-comment">channel-name</span></span></code></em><span class="hljs-comment"><span class="hljs-comment"> nixos</span></span>
</pre><p>
(Be sure to include the <code class="literal">nixos</code> parameter at the end.) For
instance, to use the NixOS 20.09 stable channel:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nix-channel --add https://nixos.org/channels/nixos-20.09 nixos</span></span>
</pre><p>
If you have a server, you may want to use the “small” channel instead:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nix-channel --add https://nixos.org/channels/nixos-20.09-small nixos</span></span>
</pre><p>
And if you want to live on the bleeding edge:
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nix-channel --add https://nixos.org/channels/nixos-unstable nixos</span></span>
</pre><p>
</p><p>
You can then upgrade NixOS to the latest version in your chosen channel by
running
</p><pre class="screen hljs nix" xml:space="preserve"><code class="prompt"><span class="hljs-comment"><span class="hljs-comment"># </span></span></code><span class="hljs-comment"><span class="hljs-comment">nixos-rebuild switch --upgrade</span></span>
</pre><p>
which is equivalent to the more verbose <code class="literal">nix-channel --update nixos;
nixos-rebuild switch</code>.
</p><div class="alert alert-info"><strong>Note:</strong>
Channels are set per user. This means that running <code class="literal"> nix-channel
--add</code> as a non root user (or without sudo) will not affect
configuration in <code class="literal">/etc/nixos/configuration.nix</code>
</div><div class="alert alert-warning"><strong>Warning:</strong>
It is generally safe to switch back and forth between channels. The only
exception is that a newer NixOS may also have a newer Nix version, which may
involve an upgrade of Nix’s database schema. This cannot be undone easily,
so in that case you will not be able to go back to your original channel.
</div><section class="section"><div class="titlepage"><div><div><h2 id="sec-upgrading-automatic" class="title" style="clear: both">4.1. Automatic Upgrades<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-upgrading-automatic" aria-label="Anchor link for: sec upgrading automatic" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
You can keep a NixOS system up-to-date automatically by adding the following
to <code class="filename">configuration.nix</code>:
</p><pre class="programlisting hljs nix" xml:space="preserve"><a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-system.autoUpgrade.enable" shape="rect"><code class="option">system.autoUpgrade.<span class="hljs-attr"><span class="hljs-attr">enable</span></span></code></a> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>;
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-system.autoUpgrade.allowReboot" shape="rect"><code class="option">system.autoUpgrade.<span class="hljs-attr"><span class="hljs-attr">allowReboot</span></span></code></a> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>;
</pre><p>
This enables a periodically executed systemd service named
<code class="literal">nixos-upgrade.service</code>. If the <code class="literal">allowReboot</code>
option is <code class="literal">false</code>, it runs <span class="command"><strong>nixos-rebuild switch
--upgrade</strong></span> to upgrade NixOS to the latest version in the current
channel. (To see when the service runs, see <span class="command"><strong>systemctl list-timers</strong></span>.)
If <code class="literal">allowReboot</code> is <code class="literal">true</code>, then the
system will automatically reboot if the new generation contains a different
kernel, initrd or kernel modules.
You can also specify a channel explicitly, e.g.
</p><pre class="programlisting hljs nix" xml:space="preserve"><a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-system.autoUpgrade.channel" shape="rect"><code class="option">system.autoUpgrade.<span class="hljs-attr"><span class="hljs-attr">channel</span></span></code></a> = https://nixos.org/channels/nixos-<span class="hljs-number"><span class="hljs-number">20.09</span></span>;
</pre><p>
</p></section></section></div><div class="part"><div class="titlepage"><div><div><div class="page-header"><h1 id="ch-configuration" class="title">Part II. Configuration<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#ch-configuration" aria-label="Anchor link for: ch configuration" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h1></div></div></div></div><div class="partintro"><div></div><p>
This chapter describes how to configure various aspects of a NixOS machine
through the configuration file
<code class="filename">/etc/nixos/configuration.nix</code>. As described in
<a class="xref" href="https://nixos.org/manual/nixos/stable/index.html#sec-changing-config" title="Chapter 3. Changing the Configuration" shape="rect">Chapter 3, <em>Changing the Configuration</em></a>, changes to this file only take
effect after you run <span class="command"><strong>nixos-rebuild</strong></span>.
</p><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-configuration-syntax" shape="rect">5. Configuration Syntax</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-package-management" shape="rect">6. Package Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-user-management" shape="rect">7. User Management</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-file-systems" shape="rect">8. File Systems</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-x11" shape="rect">9. X Window System</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-gpu-accel" shape="rect">10. GPU acceleration</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-xfce" shape="rect">11. Xfce Desktop Environment</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-networking" shape="rect">12. Networking</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-kernel-config" shape="rect">13. Linux Kernel</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#chap-pantheon" shape="rect">14. Pantheon Desktop</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-matomo" shape="rect">15. Matomo</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-nextcloud" shape="rect">16. Nextcloud</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-jitsi-meet" shape="rect">17. Jitsi Meet</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-grocy" shape="rect">18. Grocy</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-networking-yggdrasil" shape="rect">19. Yggdrasil</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-prosody" shape="rect">20. Prosody</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-prometheus-exporters" shape="rect">21. Prometheus exporters</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-weechat" shape="rect">22. WeeChat</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-taskserver" shape="rect">23. Taskserver</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-matrix" shape="rect">24. Matrix</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-gitlab" shape="rect">25. Gitlab</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-mailman" shape="rect">26. Mailman</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#trezor" shape="rect">27. Trezor</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-emacs" shape="rect">28. Emacs</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-flatpak" shape="rect">29. Flatpak</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-postgresql" shape="rect">30. PostgreSQL</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-foundationdb" shape="rect">31. FoundationDB</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-borgbase" shape="rect">32. BorgBackup</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-hidepid" shape="rect">33. Hiding process information</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-security-acme" shape="rect">34. SSL/TLS Certificates with ACME</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-programs-zsh-ohmyzsh" shape="rect">35. Oh my ZSH</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-program-plotinus" shape="rect">36. Plotinus</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-programs-digitalbitbox" shape="rect">37. Digital Bitbox</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#module-services-input-methods" shape="rect">38. Input Methods</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#ch-profiles" shape="rect">39. Profiles</a></span></dt><dt><span class="chapter"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-kubernetes" shape="rect">40. Kubernetes</a></span></dt></dl></div></div><section class="chapter"><div class="titlepage"><div><div><h2 id="sec-configuration-syntax" class="title">Chapter 5. Configuration Syntax<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-configuration-syntax" aria-label="Anchor link for: sec configuration syntax" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-configuration-file" shape="rect">5.1. NixOS Configuration File</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-module-abstractions" shape="rect">5.2. Abstractions</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-modularity" shape="rect">5.3. Modularity</a></span></dt><dt><span class="section"><a href="https://nixos.org/manual/nixos/stable/index.html#sec-nix-syntax-summary" shape="rect">5.4. Syntax Summary</a></span></dt></dl></div><p>
The NixOS configuration file
<code class="filename">/etc/nixos/configuration.nix</code> is actually a <span class="emphasis"><em>Nix
expression</em></span>, which is the Nix package manager’s purely functional
language for describing how to build packages and configurations. This means
you have all the expressive power of that language at your disposal,
including the ability to abstract over common patterns, which is very useful
when managing complex systems. The syntax and semantics of the Nix language
are fully described in the
<a class="link" href="https://nixos.org/nix/manual/#chap-writing-nix-expressions" target="_top" shape="rect">Nix
manual</a>, but here we give a short overview of the most important
constructs useful in NixOS configuration files.
</p><section class="section"><div class="titlepage"><div><div><h2 id="sec-configuration-file" class="title" style="clear: both">5.1. NixOS Configuration File<a class="anchorjs-link " href="https://nixos.org/manual/nixos/stable/#sec-configuration-file" aria-label="Anchor link for: sec configuration file" data-anchorjs-icon="" style="font-family: anchorjs-icons; font-style: normal; font-variant: normal; font-weight: normal; line-height: 1; padding-left: 0.375em;"></a></h2></div></div></div><p>
The NixOS configuration file generally looks like this:
</p><pre class="programlisting hljs" xml:space="preserve">{ config, pkgs, ... }:
{ <em class="replaceable"><code>option definitions</code></em>
}
</pre><p>
The first line (<code class="literal">{ config, pkgs, ... }:</code>) denotes that this
is actually a function that takes at least the two arguments
<code class="varname">config</code> and <code class="varname">pkgs</code>. (These are explained
later.) The function returns a <span class="emphasis"><em>set</em></span> of option definitions
(<code class="literal">{ <em class="replaceable"><code>...</code></em> }</code>). These definitions
have the form <code class="literal"><em class="replaceable"><code>name</code></em> =
<em class="replaceable"><code>value</code></em></code>, where
<em class="replaceable"><code>name</code></em> is the name of an option and
<em class="replaceable"><code>value</code></em> is its value. For example,
</p><pre class="programlisting hljs nix" xml:space="preserve">{ config, pkgs, ... }:
{ <a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-services.httpd.enable" shape="rect"><code class="option">services.httpd.<span class="hljs-attr"><span class="hljs-attr">enable</span></span></code></a> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>;
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-services.httpd.adminAddr" shape="rect"><code class="option">services.httpd.<span class="hljs-attr"><span class="hljs-attr">adminAddr</span></span></code></a> = <span class="hljs-string"><span class="hljs-string">"[email protected]"</span></span>;
<a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-services.httpd.virtualHosts" shape="rect">services.httpd.virtualHosts.localhost.<span class="hljs-attr"><span class="hljs-attr">documentRoot</span></span></a> = <span class="hljs-string"><span class="hljs-string">"/webroot"</span></span>;
}
</pre><p>
defines a configuration with three option definitions that together enable
the Apache HTTP Server with <code class="filename">/webroot</code> as the document
root.
</p><p>
Sets can be nested, and in fact dots in option names are shorthand for
defining a set containing another set. For instance,
<a class="xref" href="https://nixos.org/manual/nixos/stable/options.html#opt-services.httpd.enable" shape="rect"><code class="option">services.httpd.enable</code></a> defines a set named
<code class="varname">services</code> that contains a set named
<code class="varname">httpd</code>, which in turn contains an option definition named
<code class="varname">enable</code> with value <code class="literal">true</code>. This means that
the example above can also be written as:
</p><pre class="programlisting hljs nix" xml:space="preserve">{ config, pkgs, ... }:
{ <span class="hljs-attr"><span class="hljs-attr">services</span></span> = {
<span class="hljs-attr"><span class="hljs-attr">httpd</span></span> = {
<span class="hljs-attr"><span class="hljs-attr">enable</span></span> = <span class="hljs-literal"><span class="hljs-literal">true</span></span>;
<span class="hljs-attr"><span class="hljs-attr">adminAddr</span></span> = <span class="hljs-string"><span class="hljs-string">"[email protected]"</span></span>;
<span class="hljs-attr"><span class="hljs-attr">virtualHosts</span></span> = {
<span class="hljs-attr"><span class="hljs-attr">localhost</span></span> = {
<span class="hljs-attr"><span class="hljs-attr">documentRoot</span></span> = <span class="hljs-string"><span class="hljs-string">"/webroot"</span></span>;
};
};
};
};
}
</pre><p>
which may be more convenient if you have lots of option definitions that
share the same prefix (such as <code class="literal">services.httpd</code>).
</p><p>
NixOS checks your option definitions for correctness. For instance, if you
try to define an option that doesn’t exist (that is, doesn’t have a
corresponding <span class="emphasis"><em>option declaration</em></span>),
<span class="command"><strong>nixos-rebuild</strong></span> will give an error like:
</p><pre class="screen hljs nix" xml:space="preserve">The option `services.httpd.enable' defined <span class="hljs-keyword"><span class="hljs-keyword">in</span></span> `/etc/nixos/configuration.nix' does not exist.