Onboarding Guide for Nix Learners
This page is in active construction and welcome to feedback for any inaccuracies.
Last updated
This page is in active construction and welcome to feedback for any inaccuracies.
Last updated
Nix is a novel, functional package manager and build tool focused on reproducibility and isolation. By design, Nix builds each package in a sandbox with explicit dependencies, so “if a package works on one machine, it will also work on another” . In practice this means you can define your entire development or deployment environment in plain-text Nix files and rebuild it exactly, byte-for-byte, on any Linux or macOS machine . For example, one user notes that “Nix lets me have multiple projects on the same system that each have their own independent view of what dependencies are available” – you can run an old Python 2.7 project and a new Python 3 project side-by-side without conflict. Nix also ensures atomic upgrades and rollbacks: installing or updating a package never overwrites others, and you can instantly roll back if something breaks . In short, Nix eliminates “it works on my machine” issues by making your environment declarative (all tools and versions are described in code) and reproducible .
This guide is for developers and contributors eager to use Nix for reproducible builds and environments. You might be a programmer learning Nix for the first time, a data scientist who needs consistent tool versions, or an open-source maintainer seeking declarative deployment. No prior Nix experience is assumed – if you know basic Unix command-line usage and care about reproducibility, you’re the right audience. (Nix works on Linux and macOS, and can even be used in Windows via WSL2.) Ultimately, anyone who wants reliable, shareable development environments – from students to DevOps engineers – will benefit from Nix.
The easiest way to install Nix is via the official installer script. On Linux (with systemd), run the multi-user installer as root or with sudo:
This creates /nix/store and adds the nix command to your shell profile . On macOS, the same script works (without --daemon by default); open Terminal and run:
Then restart your shell or source the profile to get nix in your PATH . On Windows, install Nix inside WSL2 with systemd enabled: enable systemd (per Microsoft’s guide) and run the installer (with --daemon if desired) . After installation, you can verify by running nix --version or nix-env --version.
Optional configuration: To use Nix’s new “flakes” feature for reproducible projects, you’ll need to enable it in your Nix config. For example, add this line to ~/.config/nix/nix.conf:
or always run Nix with --experimental-features 'nix-command flakes'. This lets you use commands like nix flake init and nix develop (covered below).
Tip: Read the Nix manual’s Quick Start or the NixOS manual for more details. The Nix download page provides the same instructions and links to the official docs .
Once Nix is installed, try out its core commands and features:
Home Manager (per-user config): Home Manager is a Nix-based tool to manage your home directory (dotfiles, user services, personal packages) declaratively. After installing Nix, you can add the Home Manager channel and install it, then write a home.nix file describing your setup. For example, you might include home.packages = [ pkgs.tmux pkgs.vim ]; and enable programs.zsh.enable = true. Running home-manager switch will apply your config. In fact, Home Manager “provides a radically better way to manage a user’s environment for both packages and dotfiles, effectively allowing you to take a configuration-as-code approach”ghedam.at. (It works on any Linux or macOS system with Nixghedam.at.) See the Home Manager manual or tutorials for step-by-step installation.
There are many high-quality, beginner-friendly resources for Nix:
Video and interactive: YouTube has talks and tutorials from NixCon and community members (e.g. “Nix for Beginners” playlists). The NixOS Wiki lists community-curated channels (see Nix Channels). For hands-on practice, sites like NixOS Playgrounds or Replit CoCalc let you run Nix examples in a browser.
Package search: The Nixpkgs search or NixOS Packages Search is invaluable for finding Nix package names. The NixOS weekly newsletter summarizes latest news and blog posts.
Wherever possible, prefer official or well-maintained sources. The NixOS wiki and Discourse forums also maintain FAQs and tutorials. Try a few of these resources to find the explanations that suit you, and keep them handy as you learn.
Nix integrates with many developer tools and editors:
Other editors: Emacs users can use nix-emacs or use-package integrations to load environment automatically. Vim/Neovim users can rely on vim-dispatch with nix-shell. In general, any editor that launches a shell (e.g. for language servers) can benefit from a Nix shell environment. Many language LSP servers (Haskell, Rust, Python) work out-of-the-box once the tools are in the Nix shell.
Build tools: You can use Nix with CI/CD as well. For example, GitHub Actions or NixOS GitLab CI templates show how to build Nix projects in pipelines. For containerized apps, Nix can produce Docker images deterministically.
Overall, the goal is to make Nix your ambient environment: code editors and terminals automatically use the Nix-defined versions of compilers, linters, etc., so you’re always running the right toolchain.
Nix has an active, helpful community. Key places to get help:
Reddit: The subreddits /r/NixOS and /r/Nix have many users sharing tips and news. (Reddit is unofficial but often quick for beginner questions.)
GitHub: Many Nix projects are on GitHub: in particular the Nixpkgs repo and the Nix repository itself. Browse their issue trackers or Discussions pages to see ongoing work and ask development-level questions. Reporting bugs or contributing fixes on GitHub is welcome once you’re more advanced.
StackOverflow: The nix tag on StackOverflow has Q&A for common problems, though coverage is spotty. For quick issues, Discourse or Matrix is usually faster.
Weekly newsletter and blog: Keep an eye on the NixOS Weekly newsletter and the Nix blog for announcements, tutorials, and community news.
When asking questions, include relevant details (Nix version, system) and any Nix expressions you’re using. The community is generally very helpful to newcomers.
Hands-on practice will cement your Nix skills. Here are some ideas for starter projects:
Reproduce a developer environment: Pick a simple project in a language you know (e.g. a small Python or Node.js app). Write a shell.nix (or flake.nix) that provides the right compiler/interpreter and libraries. For example, make a Python shell.nix that loads Python 3 and numpy/matplotlib, then verify you can run your script. This shows off isolated, reproducible envs.
Package a command-line tool: Find a small open-source project (say, hello.c) and write a default.nix that builds it. You’ll learn how to use stdenv.mkDerivation or (easier) how to call pkgs.makeShell/pkgs.runCommand in a flake. Build it with nix-build and run the result in ./result/bin/hello. Consider contributing it to Nixpkgs if it’s missing.
Manage dotfiles with Home Manager: Install Home Manager and move one of your config files (e.g. for git or your shell) under Nix management. Declare it in home.nix and run home-manager switch. This gets you familiar with Nix expressions for user config.
Use Nix in a CI or Docker: If you have a GitHub repo, try adding a GitHub Actions step that runs a Nix build. Or use Nix to create a Docker container: e.g. nix-build '<nixpkgs/nixpkgs>' -A dockerTools.buildImage with a simple NixOS config. This shows off Nix’s declarative deployment.
Explore NixOS (optional): If you’re adventurous, try the NixOS live ISO in a VM. It’s a full Linux distro entirely configured in Nix. Even if you stick to using Nix on another distro, seeing a system configured by Nix can deepen your understanding.
As you try these projects, consult the resources above when you get stuck. The key is to start small and expand: every time you tweak shell.nix or add a package to nix-env and see it build, you’ll learn something new. Welcome to the Nix ecosystem – enjoy the journey to reproducible, declarative environments!
nix-shell (ad-hoc development shells): Run nix-shell -p pkg1 pkg2 … to drop into a temporary shell where those packages are available. For example nix-shell -p hello git starts a shell with hello and git installed. This is great for trying tools without installing them system-wide. For more complex cases, you can write a shell expression in a file (e.g. shell.nix) to declare your environment, and then just run nix-shell. See the Nix tutorials for how to write shell.nix (for example, using mkShell or mkShellNoCC) to set up projects with all needed tools.
nix-env (per-user profiles): You can install packages into your personal Nix profile. For instance, nix-env -iA nixpkgs.hello installs the hello package (via the Nixpkgs collection). Use nix-env -qaP <pattern> to search for packages. Newer Nix versions also have nix profile install (e.g. nix profile install nixpkgs.hello) which achieves the same in a more modern way. Your installed packages live in ~/.nix-profile. To upgrade, run nix-env --upgrade (or nix profile upgrade). Since Nix keeps old versions, you can always roll back by nix-env --rollback if something goes wrong.
Flakes (project pinning): Flakes are an optional Nix feature for reproducible projects. A flake is a directory (often a Git repo) containing a flake.nix and flake.lock. You can create one with nix flake init -t or manually. A flake can define outputs like devShells, packages, or NixOS configurations. For example, a simple flake.nix might declare devShells.default = mkShell { packages = [ pkgs.python39 pkgs.numpy ]; }. Then running nix develop (or nix shell .#default) will load that environment. Because flakes use a lock file, all dependencies (even the Nixpkgs version) are pinned, ensuring reproducibility. Flakes are still marked experimental in some Nix releases, but they offer a clean way to share Nix setups with others .
Each of these tools builds on the same core idea: write down what you need in Nix language, and Nix takes care of fetching/building and isolating it. As one Nix user notes, even beginners can have fully Nix-managed dev environments in about 20 minutes . In the next section we’ll list many learning resources to deepen your understanding.
Official documentation and tutorials: The NixOS website hosts guides and references. For example, “How Nix Works” explains the core principles . The Nix Pills tutorial series is a classic introduction on nixos.org . The NixOS/Nix manual pages cover commands like nix-shell and Nix expressions. The nix.dev site (community-driven) has guided tutorials (e.g. setting up shell.nix) and a full reference.
Books and guides: NixOS & Flakes Book (free online) is an unofficial beginner book covering Nix and NixOS with examples . (Its preface even invites beginners: “Looking for a beginner-friendly tutorial? Then you've come to the right place!” .) Other recommended reads include Nix Pills (as above) and Nix Cookbook (paid). For advanced learning, Learning Nix by Fumito Kowasaki (free) and various blog posts can help.
Tutorials and blogs: Many community blogs and articles walk through Nix basics. For example, Michael Lynch’s blog shows how to set up per-project environments . The blog “Reproducible Data Science with Nix” by B. Rodrigues (July 2023) has a gentle intro to using Nix for R and data projects . The official Tweag blog has a “Flakes” tutorial by Nix founder Eelco Dolstra . Searching for “Nix tutorial” or “Nix pills” will turn up more guides.
VS Code: There’s a Nix Environment Selector extension that can automatically switch your VSCode workspace to use a Nix shell . You can also use the direnv extension with nix-direnv to auto-load the shell for each project. The NixOS Wiki notes that you can use nix-direnv with the VSCode direnv extension, or the nix-env-selector extension for manual switching . If you use VSCode on NixOS, you can install vscode.fhs or use the flatpak-based /Applications with a proper NIXPATH.
Direnv and Lorri: For any shell or editor, the direnv tool works well with Nix. You can drop a .envrc in your project with use nix or use flake, and direnv will auto-load the environment. Lorri is another tool that watches your shell.nix and rebuilds it when it changes, feeding updates to direnv in the background. As described on its homepage, “lorri is a nix-shell replacement for project development” with fast direnv integration . After enabling lorri and direnv in your config, simply run lorri init in a project; from then on it will keep your dev environment in sync without blocking your terminal .
Discourse (NixOS Forum): The official NixOS Discourse forums (discourse.nixos.org) are the central Q&A site. Ask questions, browse tutorials, or read the wiki. The NixOS website explicitly points new users to the forum for “Get in Touch” .
Matrix Chat: The Nix community has Matrix (chat) rooms, e.g. #nix and #nixos on Matrix.org (accessible via matrix.to). You can ask questions in real time there. The NixOS site lists “Matrix Chat” as a primary contact option .