Improve documentation around upgrading nix #9679
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,40 @@ | ||
| # Upgrading Nix | ||
|
|
||
| > **Note** | ||
| > | ||
| > These upgrade instructions apply for regular Linux distributions where Nix was installed following the [installation instructions in this manual](./index.md). | ||
|
|
||
| First, find the name of the current [channel](@docroot@/command-ref/nix-channel.md) through which Nix is distributed: | ||
|
|
||
| ```console | ||
| $ nix-channel --list | ||
| ``` | ||
|
|
||
| By default this should return an entry for Nixpkgs: | ||
|
|
||
| ```console | ||
| nixpkgs https://nixos.org/channels/nixpkgs-23.05 | ||
| ``` | ||
|
|
||
| Check which Nix version will be installed: | ||
|
|
||
| ```console | ||
| $ nix-shell -p nix -I nixpkgs=channel:nixpkgs-23.11 --run "nix --version" | ||
|
There was a problem hiding this comment. Wouldn't it be better to link to search.nixos.org? seems like a much faster option, you could also directly link to information about the package. There was a problem hiding this comment. I try to keep the Nix manual self-contained because most of the action happens somewhere else and at a different pace. Baking in things that may get out of date or out of sync is a source of confusion I'd very much like to avoid. One point of integration for documentation is nix.dev, where we point to search.nixos.org very early on. All in all, as said in the other comment, I really don't like the vanilla upgrade story and given the lack of clearly superior approaches wouldn't want to spend too much energy on it right now. |
||
| nix (Nix) 2.18.1 | ||
| ``` | ||
|
|
||
| > **Warning** | ||
| > | ||
| > Writing to the [local store](@docroot@/store/types/local-store.md) with a newer version of Nix, for example by building derivations with `nix-build` or `nix-store --realise`, may change the database schema! | ||
| > Reverting to an older version of Nix may therefore require purging the store database before it can be used. | ||
|
|
||
| Update the channel entry: | ||
|
|
||
| ```console | ||
| $ nix-channel --remove nixpkgs | ||
| $ nix-channel --add https://nixos.org/channels/nixpkgs-23.11 nixpkgs | ||
| ``` | ||
|
|
||
| Multi-user Nix users on macOS can upgrade Nix by running: `sudo -i sh -c | ||
| 'nix-channel --update && | ||
| nix-env --install --attr nixpkgs.nix && | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems unclear why the nix version needs to be checked, is it because a "upgrade" might somehow lower the nix version?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, you should be aware which source you're getting Nix from. Software versions are a notion that only exists in users' heads.