# 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:
> - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions
> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations

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 channel’s 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:

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

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

```console
$ nix-channel --remove nixpkgs
$ nix-channel --list
```