---
name: "nix-channel"
section: "1"
platform: "linux"
package: "nix-bin"
version: "2.26.3+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/nix-channel"
---

# nix-channel(1)

manage Nix channels

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

The moving parts of channels are: - The official channels listed at ⟨https://nixos.org/channels⟩ - The user-specific list of subscribed channels ⟨#subscribed-channels⟩ - The downloaded channel contents ⟨#channels⟩ - The Nix expression search path ⟨@docroot@/command-ref/conf-file.md#conf-nix-path⟩\\c , set with the `-I` option ⟨#opt-i⟩ or the `NIX_PATH` environment variable ⟨#env-NIX\_PATH⟩

**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⟩\\c , `fetchTarball` ⟨@docroot@/language/builtins.md#builtins-fetchTarball⟩\\c , 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:

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