lix/doc/manual/src/command-ref/nix-channel.md
Valentin Gagarin ee72ede389 remove the Channels section
this is a how-to guide which should not be in the reference manual.
it also refers to `nix-env`, which should not be the first thing readers
of the reference manual encounter, as it behaves very differently in
spirit from the rest of Nix.

slightly reword the documentation to be more concise and informative.
2023-07-19 09:39:04 +02:00

3.1 KiB
Raw Blame History

Name

nix-channel - manage Nix channels

Synopsis

nix-channel {--add url [name] | --remove name | --list | --update [names…] | --list-generations | --rollback [generation] }

Description

Channels are a mechanism for referencing remote Nix expressions and conveniently retrieving their latest version. For the list of official channels, visit https://nixos.org/channels.

Note

The state of a subscribed channel is external to the Nix expressions relying on it. This may limit reproducibility.

Dependencies on other Nix expressions can be declared explicitly with:

This command has the following operations:

  • --add url [name]
    Add a channel name located at url to the list of subscribed channels. If name is omitted, default to the last component of url, with the suffixes -stable or -unstable removed.

    Note

    --add does not automatically perform an update. Use --update explicitly.

    A channel URL must point to a directory containing a file nixexprs.tar.gz. At the top level, that tarball must contain a single directory with a default.nix file that serves as the channels entry point.

  • --remove name
    Remove the channel name from the list of subscribed channels.

  • --list
    Print the names and URLs of all subscribed channels on standard output.

  • --update [names…]
    Download the Nix expressions of subscribed channels and create a new generation. Update all channels if none is specified, and only those included in names otherwise.

  • --list-generations
    Prints a list of all the current existing generations for the channel profile.

    Works the same way as

    nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
    
  • --rollback [generation]
    Revert channels to the state before the last call to nix-channel --update. Optionally, you can specify a specific channel generation number to restore.

{{#include ./opt-common.md}}

{{#include ./env-common.md}}

Files

nix-channel operates on the following files.

{{#include ./files/channels.md}}

Examples

Subscribe to the Nixpkgs channel and run hello from the GNU Hello package:

$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --list
nixpkgs https://nixos.org/channels/nixpkgs
$ nix-channel --update
$ nix-shell -p hello --run hello
hello

Revert channel updates using --rollback:

$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
"22.11pre296212.530a53dcbc9"

$ nix-channel --rollback
switching from generation 483 to 482

$ nix-instantiate --eval '<nixpkgs>' --attr lib.version
"22.11pre281526.d0419badfad"

Remove a channel:

$ nix-channel --remove nixpkgs
$ nix-channel --list