It’s documented in the manual: https://github.com/nix-community/home-manager/archive/release-24.05.tar.gz
Unrelated, but using builtins.fetchTarball without a hash means that nix will re-download that tarball and fully rebuild everything depending on it whenever the download cache lapses, which means every hour or so.
This means that your system basically updates home-manager every hour without any explicit action on your end, and it’s impossible to reproduce your build.
You should probably add the hash, or use npins to import home-manager instead.
Unless you intend to have mini-modules all over your NixOS config, I’d also suggest putting your home-manager config module in a separate file, that way the separation between NixOS and home-manager stays much clearer in the long term:
Thank you for the explanation why I should add a hash - but as a newbie I have no clear understanding where I should add it (I did read the language manual cursorily, but do not remember all - I have a faint idea, what a hash does ---- sorry, but nix is a lot to learn!), could you write the corrected line for me? Thank you.
Would use of npins - which I have not yet tried - be better? and how would it be done?
I did the replacement of the tarbal, as you suggest, but now get the error:
error: The option home-manager.users' in /nix/store/w3lblmxf340bhxz8mkgpdf95gccxkcaf-source/nixos/common.nix’ is already declared in `/nix/store/1m3xkp0fingsbsswmp09s3m8q64gkcq8-source/nixos/common.nix’.
What did I do wrong?
I will follow you suggestion and but the home-manger code in a separate file. Learning is a slow process…
Right, a hash in general is exactly what it is elsewhere, a number represented as a string which uniquely identifies a file by doing some math to condense it. You can calculate a sha256 hash for any old file with sha256sum <file> (other hashes exist).
Nix uses hashes to produce a unique path for each file in the nix store, even if the file name would otherwise be the same - if a file has a different hash, it’s different, so you can uniquely identify two different versions of the same file, even if they don’t have different version numbers. This is important for nix to be able to - among other things - let you effortlessly use two different versions of the same library, which is one of its killer features.
The error message you show actually contains a nice example:
Note the seemingly random string of characters before the file name? That’s a hash, in nix’ slightly bespoke representation that tries to avoid Dutch swearwords because it originates in a PhD thesis from a Dutch university. Probably one of my favorite little personal touches from eelco, it’s delightfully silly.
For files downloaded from the internet, nix cannot compute a hash for you - after all, it doesn’t have the files. Yet to guarantee a unique path into which to store the downloaded file, it needs that hash.
Nix can download the file and compute the hash afterwards, but if it does that, and places it in the store, there’s no way for it to find that file in the store again without recomputing the hash - for which the file needs to be downloaded again (or taken from the download cache). This causes the problems I mention.
It’s also just bad practice to download files without a hash, without one you never know if the file changed without your knowledge, which can be bad if you e.g. download it from a different network where someone has a MITM attack running to change it, or if the file is corrupted during transmission or such. That’s why for OS images and such you’ll often get a hash with the file.
Not so with a constantly updated git repo branch tarball though. We’ll have to compute it ourselves.
Well, the problem with the above approach is that now everytime you want to update you’ll have to manually go through that, fetch the newest hash and update the string.
This is alright for only one or two tarballs, but that number can grow quickly.
npins is basically a little CLI tool that stores all your fetchTarballs in a json file, including the URL to download and the expected hash. It then has a few subcommands to update hashes for you. It also has some convenience functions so you don’t have to figure out e.g. how to get a tarball for a branch from git.
That will edit your $NIX_PATH to always point to the versions of inputs from npins, which means you’ll be able to use the <> syntax instead of manually import-ing from tarballs:
let
home-manager = import <home-manager/nixos>;
Note that this is not using channels. Unfortunately using NIX_PATH is still necessary to work around limitations of nixos-rebuild, until someone makes NixOS evaluation npins-compatible, or flakes become more stable, there isn’t really a better way.
It also includes a guide on how to change nix config so e.g. nix-shell also uses the fixed tarballs - otherwise you will still need to manage channels to update those commands.
I really need to finish this book on NixOS that just teaches these things to begin with, this is waaaay to complex to repeat in comments every few days x)
I’m not 100% sure, but there are some spurious quotes in there. Can you double check that’s the exact error? And maybe copy your config again, making sure it’s the whole thing?
I did not see your help with the tarbal hash, which I computed as you suggest and inserted it. npins is for now (I am in day 6 of nixos!) overwhelming and I have so far only one tarbal. will deal with the update issue when I come to it.
what should I read to understand how I update NixOS and how do I keep it current to avoid hacking?
Thank you for your help - and please write a book of how to start with NixOS without falling into every lurching trap!
“Channels” are basically just a file in a given user’s home directory that tells nix how to link up names you put in <> to specific local directories. nixos-rebuild will automatically use the nixpkgs name to figure out what to use to build your system.
Since everything ultimately comes from the root users’ nixpkgs channel, updating it, and then rebuilding your system, will update your system.
The big thing to realize about channels is that every user on your system has independent channels - this means that not using sudo will manipulate your users’ channels, which are not used for your system config. This is easy to overlook, and the source of most issues with them.
In addition, every 6 months there is a new NixOS release - you need to switch to a different channel when that happens, and read the release notes to update any configuration that is no longer compatible. Make sure to come back for that. The next release will be 24.11 - in November/December if the number isn’t clear
They have their issues, but channels aren’t the worst thing. While we’re waiting for better tools to be developed it’s probably the best option as a complete newcomer.
In general, the NixOS manual is probably still the best resource we have, despite being more of a reference manual. The first chapter is helpful. Just don’t read too far down, it’ll just confuse you.
Yeah, I noticed that too. I’ve only recently started recommending them because I think they are the best option currently. Unfortunately the UX for using them on NixOS isn’t there yet - I think we could make nixos-rebuild npins-aware to solve that in the longer term.
