nixos/nix.dev

Official documentation for getting things done with Nix.

nix.dev

Official documentation for getting things done with Nix.

Contributing

Content is written in MyST, a superset of CommonMark. For its syntax, see the MyST docs.

For contents and style see contribution guide.

Local preview

Run nix-shell --run devmode and open a browser at http://localhost:5500.

As you make changes your browser should auto-reload within a few seconds.

To manually test redirects:

nix-shell -p netlify-cli --run "cd result; netlify dev"

nix.dev's Issues

Windows WSL2 doesn't support --daemon

On https://nix.dev/tutorials/install-nix.html

WSL2 (the latest version of WSL on Windows) doesn't have systemd, so I need to pass --no-daemon . I don't have a WSL install to test if that supports --daemon I'm afraid.

Seeing as WSL is intended (I think) as a single-user distro mostly anyway (each windows user gets their own linux installation), I don't think this will be a major problem.

Do you have a one-liner to reproduce this?

That's how we can pitch Nix reproducibility.

NixOS tests

gitignore + cleanSource + ??

Debugging Nix expressions

What to do when things go wrong?

• benchmarking
• "my build failed now what?"
• I get a weird error

NixOS/nixpkgs#62913

Developer environments

Provide default.nix or flake.nix

This should only be a tiny wrapper around requirements.nix to follow the convention.

Motivated by the discussion in NixOS/nixos-homepage#443

Expand the introduction to better set out the goals and explain who it is for (people new to Nix)

Use of anti-patterns in the tutorials

The tutorials contain occurences of the anti-patterns. For example, Pinning Nixpkgs contains:

with import (fetchTarball https://github.com/NixOS/nixpkgs/archive/nixos-20.03.tar.gz) {};

stdenv.mkDerivation { … }

which groups 2 anti-patterns:

• Unquoted URLs
• with attrset; ... expression

Would you like a PR fixing those?

Homebrew to Nix migration

• https://www.youtube.com/watch?v=NYyImy-lqaA
• https://www.softinio.com/post/moving-from-homebrew-to-nix-package-manager/
• zupo/dotfiles@43a4e46

Anti pattern: language features

• unquoted URLs
• with

Using fakeSha256 when updating derivations

I'm not entirely sure what the precise underlying cause is of this behavior, but I've noticed the following non-obvious gotcha when updating Nix derivations in the past:

1. Modify a derivation somehow
   • e.g. bump a package version, either fetching a binary to patchelf, updating some Haskell dependency, etc.
2. Forget to modify the sha256 field
   • That is to say, the valid sha256 associated with the previously working derivation remains
3. Build the derivation
   • The derivation actually does build, leading developer to believe that their change was effective
4. Attempt to use the derivation, observing that the result from the previously successful derivation is the one being pulled from the store

---

A behavioral reproduction:

1. Clone nixpkgs and cd into the directory
   • The patches below specifically refer to the nixpkgs-unstable branch as of 13 June 2020
   • Relevant commit hash is dcb64ea42e64aaecd8e6fef65cc86245c9666818
2. Apply the following (incorrect) patch

incorrect patch

diff --git a/pkgs/applications/misc/hello/default.nix b/pkgs/applications/misc/hello/default.nix
index 32c8c696..e3555418 100644
--- a/pkgs/applications/misc/hello/default.nix
+++ b/pkgs/applications/misc/hello/default.nix
@@ -2,7 +2,7 @@
 
 stdenv.mkDerivation rec {
   pname = "hello";
-  version = "2.10";
+  version = "2.9";
 
   src = fetchurl {
     url = "mirror://gnu/hello/${pname}-${version}.tar.gz";

3. Run the following command and observe that the version is still 2.10

nix-shell -E '{pkgs ? import ./. {}}: pkgs.mkShell { buildInputs = [ pkgs.hello ]; }' --command 'hello --version'

4. Drop the previous patch and apply the following (correct) patch

correct patch

diff --git a/pkgs/applications/misc/hello/default.nix b/pkgs/applications/misc/hello/default.nix
index 32c8c696..c0f60198 100644
--- a/pkgs/applications/misc/hello/default.nix
+++ b/pkgs/applications/misc/hello/default.nix
@@ -2,11 +2,11 @@
 
 stdenv.mkDerivation rec {
   pname = "hello";
-  version = "2.10";
+  version = "2.9";
 
   src = fetchurl {
     url = "mirror://gnu/hello/${pname}-${version}.tar.gz";
-    sha256 = "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i";
+    sha256 = "19qy37gkasc4csb1d3bdiz9snn8mir2p3aj0jgzmfv0r2hi7mfzc";
   };
 
   doCheck = true;

5. Run the following command and observe that the version is now (correctly) 2.9

nix-shell -E '{pkgs ? import ./. {}}: pkgs.mkShell { buildInputs = [ pkgs.hello ]; }' --command 'hello --version'

---

I think having a worked out example (like the one above) would help, but an explanation of Nix's underlying behavior here would be very nice as well.

fully reproducible example not reproducible

The following is a fully reproducible example https://github.com/domenkozar/nix.dev/blob/96302feb9bac102d6eb207a4f468efcaabed8fb1/source/tutorials/ad-hoc-developer-environments.rst#towards-reproducibility

No

git version 2.25.0

git version 2.25.4

nix-diff tutorial

Anti pattern: nesting multi-line quotations

patchelfing

https://brianmckenna.org/blog/running_binaries_on_nixos

https://github.com/svanderburg/nix-patchtools

Explain (briefly) how to get an archive link

In https://nix.dev/tutorials/ad-hoc-developer-environments.html#towards-reproducibility , nixpkgs is explictly set to an archive link.

It would be nice if it was described how to get this link -- even better if nix had an easy way of providing it, so I could quickly snapshot "my current" nix install to send to other people.

Anti pattern: nix-channel command

• NixOS/nix#3601

Anti pattern: // operator

Does not perform deep merge.

Anti pattern: rec

Reducing closure size

anti pattern: ./.

<nixpkgs>: say what's the recommended approach

Getting started with Nix template repository

• (periodically) update to latest all-tests-passing commit in the chosen NixOS release branch. Bonus karma points to show how to setup a GitHub Action that opens a PR to bump the commit on the first of every month.

https://github.com/marketplace/actions/create-pull-request

https://github.blog/2020-06-22-promote-consistency-across-your-organization-with-workflow-templates/

Writing convenient unix utilities in nix

I have a conundrum! I would really appreciate some words of wisdom from nix gurus.

I am writing some data-analysis utilities that are glued together with nix and I am wondering about the best way to provide simple user-interfaces for them (e.g. from the unix shell.)

For example, I have a utility that processes profiler data files to produce textual reports (similar to perf report), and the current user-interface is like this:

$ nix-build -E '(import studio/tools/vmprofiler {}).analyze_dir(/var/run/snabb/12345/engine/vmprofile)'

but that's quite verbose and users would probably much prefer a usage like:

$ vmprofiler -i /var/run/snabb/12345/engine/vmprofile -o .

and now I am wondering how to at least partially bridge that gap so that the command-line interface won't be a barrier to adoption of the tools.

I suppose that I have at least three potential ways to make a shell script wrapper:

• Make it use the #!nix-shell shebang to run the tools directly with the right env.
• Make it call nix-build directly in the script (wrapper to current usage.)
• Make it into a nix package that is installed with nix-env.

I am somewhat drawn to calling nix-build because I like the idea of copying the input data into the nix store. These tools can potentially operate on large amounts of data that requires expensive preprocessing and I'd love for nix to transparently cache this intermediate processing. So while I want to have a convenient user-interface I am also happy to have nix as a runtime dependency and to use it as effectively as possible.

Does anybody see the dilemma and have an idea for how to sort it out?

Here are a couple of the scripts I am talking about:

• timeliner/default.nix
• vmprofiler/default.nix

"The problem" is to provide command-line usage instructions that won't make people go "ugh" and also won't give up nice benefits of deep nix integration.

Developing for NixOS

or developing portable software

@domenkozar do you want to make a tutorial out of this?

https://discourse.nixos.org/t/developing-for-nixos/8189

gotcha: paranthesis in lists

https://twitter.com/AsheshAmbasta/status/1281465163565150210

Deploy basic server to AWS

• via terraform?
• via nixops?

Incorrect (?) section about adding binary caches

In faq.rst there is a section about binary caches:

How do I add a new binary cache?
Using Nix:
$ echo "trusted-binary-caches = https://hydra.snabb.co" >> /etc/nix/nix.conf

This doesn't seem correct, because single-user Nix doesn't use /etc/nix by default (only when NIX_CONF_DIR environment variable is set to /etc/nix, tested on 1.11.15) - I'm not sure what directory it uses then.

It might make sense to add "set environment variable NIX_CONF_DIR to /etc/nix in your bashrc" to this section, but I'm not sure what other side effects in will bring.

Guide on packaging stuff that doesn't fit into Nix model (steam, electron)

Use poetry2nix?

I would like to demonstrate https://jupyter-sphinx.readthedocs.io , however, building it won't work "out-of-the-box" because flit is used somewhere and pypi2nix does not like that.

IMO we should avoid using pypi2nix and use poetry2nix instead as that one builds upon a common and well-functioning tool, poetry.

Of course, if this were to move into Nixpkgs we may as well use Nixpkgs' packages.

@adisbladis I suppose when PEP 517/518 is used, we need to override and set format in buildPythonPackage or does poetry2nix do this automatically?

Referencing the channel:* syntax

Hi,

I recently learned about the channel:* syntax to reference a channel without the need to specify a full URL. I used it like this

$ nix-build -I nixpkgs=channel:nixos-unstable '<nixpkgs>' -A calibre

to check if calibre builds in the nixos-unstable channel.

The Pinning Nixpkgs tutorial doesn't mention this syntax. Do you want a PR to add it?

What are collisions and what do I do about them?

Feedback on reproducible shells

Why might it be useful to run the bash hook every time I run the shell (I imagine it can be used as part of git workflows etc, but mentioning a 'real world' example to supplement the 'hello' demonstration would help clarify this I think

Why is the direnv command useful - I imagine developers would not need to modify their project shell.nix file that often and would probably restart the shell at least daily when they begin working on a project anyway? Or is that not a common workflow and therefore it's worth installing direnv globally on all dev machines to avoid having to restart the shell?

Cross compile

Github Actions tutorial

Gabriel: One nice benefit of Nix is that CI can build and cache developer environments for every project on every branch

<nixos> can also be avoided

https://twitter.com/zimbatm/status/1272582711178342403

License, CLA

The used license is more restrictive than the GPL and not even considered open source. It don't fit the ecosystem and is not compatible with the license of the nixos website.

I suggest to use the same license as the website (CC BY-SA) since the plan is to integrate the content there.

And what is the plan with the CLA? Do you want to get rich by selling the tutorials as book or add a paywall later?

I don't want to give you the copyright but share it freely with the community, so anyone could sell locally printed books if there is demand for that. That's better for the environment and more fair.

<nixpkgs>: what to do with NixOS bare machines?

That one is tricky because be design nixos-rebuild depends on $NIX_PATH.

There are a few ways forward:

a) Flakes will solve this with locking, but they are not released yet.

b) For legacy we could change nixos-rebuild to look for /etc/nixos/nixpkgs.nix and use it to import <nixpkgs>.

c) Without changing upstream, one can create a wrapper called nixos-rebuild that sets $NIX_PATH to point to a commit and calls the original nixos-rebuild command. Not ideal since it won't do the right thing on the first installation, but the second will do.

Anti pattern: imperative package management

Anti pattern: relying on <nixpkgs>

Anti pattern: ...

Guide on speeding up CI builds

Would be great with a guide (building on the CI with Cachix guide) that shows how to speed up CI, like minimizing rebuilds, making tests be derivations, and reducing cache fetching. This thread sparked some discussion.

Add tutorial on creating a Nix channel

It'd be nice to have a tutorial on nix.dev dedicated to both creating and consuming your own Nix channel, preferably with a kind of "progressive" logic. Maybe something along these lines:

1. Create new channel via GitHub with a single helloWorld package (just a basic default.nix)
2. Add the channel on the command line and build the helloWorld package (i.e. `nix-build '' -A helloWorld')
3. Use the channel to do a real Nix build (i.e. to create a package that consumes helloWorld, maybe a Docker container or something)
4. Update the channel to expose a pinned nixpkgs
5. Update the channel again to include an overlay on the pinned nixpkgs
6. Use Niv to provide pinned access to the channel.

I'd be happy to do the work, just wanted to see if others would find this helpful. And open to suggestions on content, of course.

Patterns: patching upstream software

https://twitter.com/amanjeev/status/1333419722768048129

fetching sources

fetchurl, fetchgit, fetchFromGitHub, etc

Getting the URL of the system channel as a regular user?

How to do this? I could run:

$ sudo nix-channel --list

And add this command to sudoers.

Or set appropriate permissions for /root (701) and /root/.nix-channels (644), and read that file directly.

But both these solutions seem hacky. =)

Can't reproduce myapp Flask example

I'm following the steps in the dev-environment tutorial. I correctly get a ./result directory but:

$ ./result/bin/myapp 
Traceback (most recent call last):
  File "/nix/store/wx3vrgfya66fp5qb6bd20y1wxkhqw4sg-myapp-0.1/bin/.myapp-wrapped", line 6, in <module>
    from myapp import run
ModuleNotFoundError: No module named 'myapp'

I was expecting the application to start.

Also, the following steps don't seem to do anything:

$ nix-shell default.nix 
Sourcing python-recompile-bytecode-hook.sh
Sourcing python-remove-tests-dir-hook
Sourcing python-catch-conflicts-hook.sh
Sourcing python-remove-bin-bytecode-hook.sh
Sourcing setuptools-build-hook
Using setuptoolsBuildPhase
Using setuptoolsShellHook
Sourcing pip-install-hook
Using pipInstallPhase
Sourcing python-imports-check-hook.sh
Using pythonImportsCheckPhase
Sourcing python-namespaces-hook
Sourcing setuptools-check-hook
Using setuptoolsCheckPhase
Executing setuptoolsShellHook
Obtaining file:///tmp/flask
Installing collected packages: myapp
  Running setup.py develop for myapp
Successfully installed myapp
Finished executing setuptoolsShellHook
$ python3 main.py 
$ echo $?
0

I'm following nixos-unstable.

Building and running docker images

Example from https://fridh.github.io/nix-tutorials/tutorials/03-images/01-creating-a-docker-image.html

Move over wiki cookbooky content

https://github.com/NixOS/nixpkgs/milestones/Move%20the%20wiki!