nix-super/doc/manual/src/command-ref/nix-channel.md
Eelco Dolstra 802150f987
<replaceable> -> <emphasis>
Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.
2020-07-23 18:27:20 +02:00

3.1 KiB
Raw Blame History

nix-channel

1

Nix

nix-channel

manage Nix channels

nix-channel

--add

url

name

--remove

name

--list

--update

names

--rollback

generation

Description

A Nix channel is a mechanism that allows you to automatically stay up-to-date with a set of pre-built Nix expressions. A Nix channel is just a URL that points to a place containing a set of Nix expressions. See also ???.

To see the list of official NixOS channels, visit https://nixos.org/channels.

This command has the following operations:

  • --add url [name]
    Adds a channel named name with URL url to the list of subscribed channels. If name is omitted, it defaults to the last component of url, with the suffixes -stable or -unstable removed.

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

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

  • --update [names…]
    Downloads the Nix expressions of all subscribed channels (or only those included in names if specified) and makes them the default for nix-env operations (by symlinking them from the directory ~/.nix-defexpr).

  • --rollback [generation]
    Reverts the previous call to nix-channel --update. Optionally, you can specify a specific channel generation number to restore.

Note that --add does not automatically perform an update.

The list of subscribed channels is stored in ~/.nix-channels.

Examples

To subscribe to the Nixpkgs channel and install the GNU Hello package:

$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
$ nix-env -iA nixpkgs.hello

You can revert channel updates using --rollback:

$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
"14.04.527.0e935f1"

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

$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
"14.04.526.dbadfad"

Files

  • /nix/var/nix/profiles/per-user/username/channels
    nix-channel uses a nix-env profile to keep track of previous versions of the subscribed channels. Every time you run nix-channel --update, a new channel generation (that is, a symlink to the channel Nix expressions in the Nix store) is created. This enables nix-channel --rollback to revert to previous versions.

  • ~/.nix-defexpr/channels
    This is a symlink to /nix/var/nix/profiles/per-user/username/channels. It ensures that nix-env can find your channels. In a multi-user installation, you may also have ~/.nix-defexpr/channels_root, which links to the channels of the root user.

Channel format

A channel URL should point to a directory containing the following files:

  • nixexprs.tar.xz
    A tarball containing Nix expressions and files referenced by them (such as build scripts and patches). At the top level, the tarball should contain a single directory. That directory must contain a file default.nix that serves as the channels “entry point”.