The examples in the flake docs are all unrunnable

I realize Nix isn’t known for good documentation or friendly error messages, but I can’t even run the simplest examples from the “nix shell” docs:

https://releases.nixos.org/nix/nix-2.19.1/manual/command-ref/new-cli/nix3-shell.html

First example from the wiki:

$ nix shell nixpkgs#youtube-dl
error: experimental Nix feature 'nix-command' is disabled; use '--extra-experimental-features nix-command' to override

Okay…

$ nix --extra-experimental-features nix-command shell nixpkgs#youtube-dl
error: experimental Nix feature 'flakes' is disabled; use '--extra-experimental-features flakes' to override

Still more? Why are all these overrides needed to run the most basic functionality and aren’t even mentioned in the docs?

Then taking the first shebang example from that same page:

$ cat test.sh
#! /usr/bin/env nix
#! nix shell github:tomberek/-#python3With.prettytable --command python

import prettytable

# Print a simple table.
t = prettytable.PrettyTable(["N", "N^2"])
for n in range(1, 10): t.add_row([n, n * n])
print t

$ chmod +x test.sh

$ ./test.sh
error: './test.sh' is not a recognised command
Try 'nix --help' for more information.

What kind of error is that? If the basic interface is really changing that much, why aren’t the docs being updated??

3 Likes

The examples in the flake manual assume that you have set experimental-features = nix-command flakes at least via your nix configuration, usually found at /etc/nix/nix.conf or ~/.config/nix/nix.conf and on NixOS managed through nix.settings.

I can not say anything about the shebang thing though. I am not a friend of that feature and prefer to write proper derivations for my scripts. Still I assume that this will be ffixed by setting the proper experimental features.

Why is a reference manual assuming things like that? How is a new user supposed to know that?

2 Likes

Never mind, you can just ignore this thread. I’m just going to try guix instead. Sorry for taking out my frustration here.

2 Likes

The reference manual has a big disclaimer at the top. Telling you that flakes are an experimental feature. Just follow the link, and it will tell you more.

These aren’t basic functionality, per se, as flakes and the nix3 CLI are both experimental features since 2021-ish… once the interface is actually stabilized, the additional experimental-features bit would no longer be needed.

But yes, the docs could be improved here.