Preface

The Pain of NixOS Beginners - Documentation and Flakes

NixOS is a highly distinctive Linux distribution built upon the Nix package manager, with a design philosophy that sets it apart from traditional distributions like Ubuntu, CentOS, Arch Linux and others.

One of NixOS's major advantages over other distributions lies in its reproducibility and declarative configuration, allowing users to replicate consistent system environments across multiple machines.

While NixOS is powerful, its strength also comes with increased system complexity. This makes it more challenging for newcomers. One major challenge is that the knowledge accumulated on other Linux distributions is not easily transferable to NixOS. Another is that official and community documentation is often scattered and outdated. These issues have troubled many NixOS beginners.

One can observe these issues with the experimental feature of the Nix package manager called Flakes. Inspired by package managers like npm and Cargo, Flakes uses flake.nix to record all external dependencies and flake.lock to lock their versions. This significantly enhances the reproducibility and composability of the Nix package manager and NixOS configurations.

Flakes' advantages have made it widely popular within the community: according to official surveys, over half of the new Nix repositories created on GitHub now utilize Flakes.

However, to maintain stability, the official documentation covers barely any Flakes-related content. This has left many Nix/NixOS users feeling confused. They see everyone using Flakes and want to learn it too, but find nowhere to start, often having to piece together scattered information, search through Nixpkgs source code, or seek help from more experienced users.

The Origin of This Book

This book originated from my scattered notes when I first started with NixOS.

In April of this year (2023), when I got into NixOS, I fell in love with its design philosophy. At the recommendation of a friend, I learned about Nix's Flakes experimental feature. After comparing Flakes with the traditional NixOS configuration method, I realized that only a Flakes-enabled NixOS met my expectations. Consequently, I completely ignored the traditional Nix configuration approach and directly learned to configure my NixOS system using Flakes during my initial steps.

Throughout my learning process, I found that there were very few beginner-friendly Flakes resources. The vast majority of documentation focused on the traditional Nix configuration approach, forcing me to extract the information I needed from various sources such as the NixOS Wiki, Zero to Nix, Nixpkgs Manual, and Nixpkgs source code while disregarding any non-Flakes-related content. This learning journey was quite convoluted and painful. To prevent future stumbling, I diligently documented numerous scattered notes as I progressed.

With some experience under my belt, in early May of this year, I switched my main PC to NixOS. After organizing and refining my NixOS newcomer notes, I published them on my blog¹ and shared them in the NixOS Chinese community. The Chinese community responded positively, and based on their advice, I translated the article into English and shared it on Reddit, receiving strong feedback².

The positive reception of this shared document encouraged me and drove me to continue improving it. Through continuous updates, the content of this document expanded to over 20,000 words. Some readers suggested that the reading experience could be improved, leading me to their suggestions³. As a result, I migrated the article's content to a GitHub repository, established a dedicated documentation site, and adjusted the presentation to make it more aligned with a beginner's guide rather than a personal notebook.

And so, a bilingual open-source book was born, which I named "<NixOS & Flakes Book>" with the Chinese title "NixOS & Flakes 新手指南" ("NixOS & Flakes Beginner's Guide").

This open-source book's content evolved step by step as I used NixOS and engaged with readers. The sense of accomplishment from readers' positive feedback has been my greatest motivation for updates. Some readers' feedback has been immensely helpful in its "evolution." Initially, I only wanted to share my experiences with NixOS in a somewhat casual manner, but it unexpectedly turned into an open-source book. Its readership abroad even surpassed that within my own country, and it garnered many stars - a result I never anticipated.

I am grateful to all friends who have contributed to this book and offered suggestions, and I appreciate all the support and encouragement from the readers. Without all of you, this book's content might have remained confined to my personal blog, and it wouldn't have reached its current form.

The Features of This Book

Focused on NixOS and Flakes, disregarding the traditional Nix configuration approach.
Beginner-friendly, with explanations from the perspective of NixOS newcomers who have some experience with Linux usage and programming.
Step-by-step, progressive learning.
Most of the chapters in this book provide reference links at the end, making it easy for readers to delve deeper into the topics and evaluate the content's credibility.
Coherent content, well-organized, and structured. Readers can either read the book gradually or quickly find the information they need.

Donation

If you find this book helpful, please consider donating to support its development.

GitHub: https://github.com/sponsors/ryan4yin
Patreon: https://patreon.com/ryan4yin
Buy me a coffee: https://buymeacoffee.com/ryan4yin
爱发电: https://afdian.net/a/ryan4yin
Ethereum: 0xB74Aa43C280cDc8d8236952400bF6427E4390855

Feedback and Discussion

I’m not an expert on NixOS, and I’ve only been using NixOS for less than 9 months until now(2024-02), so there must be some misconceptions or complex cases in the book. If anyone finds anything incorrect or have any questions / suggestions, just let me know about it by opening an issue or joining the discussion on GitHub Discussions. I'm happy to continue improving the content of this book.

The reason why I wrote this little book was only because no one in the community did it for me, who was a beginner at the time, so I chose to do it myself. Even though I knew I could make mistakes, it's much better than doing nothing.

My hope is that this book can help more people, enabling them to experience the joys of NixOS. Hope you like it!

Historical Feedback and Discussions on This Book

English feedback and related discussions:

Chinese feedback and discussions:

8.0 KiB Raw Blame History Unescape Escape