nix-super/doc/manual/src/command-ref/nix-channel.md

# Name

`nix-channel` - manage Nix channels

# Synopsis

`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.

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:

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

You can revert channel updates using `--rollback`:

```console
$ 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

  - `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/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
    `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/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 channel’s “entry point”.
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								# Name
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								`nix-channel` - manage Nix channels
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								# Synopsis
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
+								`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] }
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								# 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.
 								To see the list of official NixOS channels, visit
 								<https://nixos.org/channels>.
 								This command has the following operations:
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--add` *url* \[*name*\]\
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								    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.
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--remove` *name*\
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								    Removes the channel named *name* from the list of subscribed
 								    channels.
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--list`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    Prints the names and URLs of all subscribed channels on standard
 								    output.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--update` \[*names*…\]\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    Downloads the Nix expressions of all subscribed channels (or only
-												<replaceable> -> <emphasis>

Pandoc doesn't know <replaceable> so let's force it to be rendered as
italics.

											
										
										
											2020-07-23 15:28:05 +03:00
+								    those included in *names* if specified) and makes them the default
 								    for `nix-env` operations (by symlinking them from the directory
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    `~/.nix-defexpr`).
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `--rollback` \[*generation*\]\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    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:
-												Enable syntax highlighting

											
										
										
											2020-07-31 16:43:25 +03:00
+								```console
 								$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
 								$ nix-channel --update
 								$ nix-env -iA nixpkgs.hello
 								```
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								You can revert channel updates using `--rollback`:
-												Enable syntax highlighting

											
										
										
											2020-07-31 16:43:25 +03:00
+								```console
 								$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
 								"14.04.527.0e935f1"
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
-												Enable syntax highlighting

											
										
										
											2020-07-31 16:43:25 +03:00
+								$ nix-channel --rollback
 								switching from generation 483 to 482
-												Clean up the manpages

											
										
										
											2020-07-24 13:56:19 +03:00
-												Enable syntax highlighting

											
										
										
											2020-07-31 16:43:25 +03:00
+								$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
 								"14.04.526.dbadfad"
 								```
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
 								# Files
-												Fix more profile dirs in docs

Picking up where #8078 left off.

											
										
										
											2023-03-27 19:05:43 +03:00
+								  - `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/channels`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    `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.
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `~/.nix-defexpr/channels`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    This is a symlink to
-												Fix more profile dirs in docs

Picking up where #8078 left off.

											
										
										
											2023-03-27 19:05:43 +03:00
+								    `${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/channels`. It ensures that
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    `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:
-												Replace the trailing markdown spaces by a backslash

They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).

											
										
										
											2021-04-23 15:30:42 +03:00
+								  - `nixexprs.tar.xz`\
-												Convert commands

											
										
										
											2020-07-23 13:58:42 +03:00
+								    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 channel’s “entry point”.