<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-nix-channel"> <refmeta> <refentrytitle>nix-channel</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class="source">Nix</refmiscinfo> <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> </refmeta> <refnamediv> <refname>nix-channel</refname> <refpurpose>manage Nix channels</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>nix-channel</command> <group choice='req'> <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg> <arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg> <arg choice='plain'><option>--list</option></arg> <arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg> <arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg> </group> </cmdsynopsis> </refsynopsisdiv> <refsection><title>Description</title> <para>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 both a set of Nix expressions and a pointer to a binary cache. <phrase condition="manual">See also <xref linkend="sec-channels" />.</phrase></para> <para>This command has the following operations: <variablelist> <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term> <listitem><para>Adds a channel named <replaceable>name</replaceable> with URL <replaceable>url</replaceable> to the list of subscribed channels. If <replaceable>name</replaceable> is omitted, it defaults to the last component of <replaceable>url</replaceable>, with the suffixes <literal>-stable</literal> or <literal>-unstable</literal> removed.</para></listitem> </varlistentry> <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term> <listitem><para>Removes the channel named <replaceable>name</replaceable> from the list of subscribed channels.</para></listitem> </varlistentry> <varlistentry><term><option>--list</option></term> <listitem><para>Prints the names and URLs of all subscribed channels on standard output.</para></listitem> </varlistentry> <varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term> <listitem><para>Downloads the Nix expressions of all subscribed channels (or only those included in <replaceable>names</replaceable> if specified) and makes them the default for <command>nix-env</command> operations (by symlinking them from the directory <filename>~/.nix-defexpr</filename>).</para></listitem> </varlistentry> <varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term> <listitem><para>Reverts the previous call to <command>nix-channel --update</command>. Optionally, you can specify a specific channel generation number to restore.</para></listitem> </varlistentry> </variablelist> </para> <para>Note that <option>--add</option> does not automatically perform an update.</para> <para>The list of subscribed channels is stored in <filename>~/.nix-channels</filename>.</para> </refsection> <refsection><title>Examples</title> <para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para> <screen> $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable $ nix-channel --update $ nix-env -iA nixpkgs.hello</screen> <para>You can revert channel updates using <option>--rollback</option>:</para> <screen> $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.nixpkgsVersion' "14.04.527.0e935f1" $ nix-channel --rollback switching from generation 483 to 482 $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.nixpkgsVersion' "14.04.526.dbadfad" </screen> </refsection> <refsection><title>Files</title> <variablelist> <varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term> <listitem><para><command>nix-channel</command> uses a <command>nix-env</command> profile to keep track of previous versions of the subscribed channels. Every time you run <command>nix-channel --update</command>, a new channel generation (that is, a symlink to the channel Nix expressions in the Nix store) is created. This enables <command>nix-channel --rollback</command> to revert to previous versions.</para></listitem> </varlistentry> <varlistentry><term><filename>~/.nix-defexpr/channels</filename></term> <listitem><para>This is a symlink to <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It ensures that <command>nix-env</command> can find your channels. In a multi-user installation, you may also have <filename>~/.nix-defexpr/channels_root</filename>, which links to the channels of the root user.</para></listitem> </varlistentry> </variablelist> </refsection> <refsection><title>Channel format</title> <para>A channel URL should point to a directory containing the following files:</para> <variablelist> <varlistentry><term><filename>nixexprs.tar.xz</filename></term> <listitem><para>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 <filename>default.nix</filename> that serves as the channel’s “entry point”.</para></listitem> </varlistentry> <varlistentry><term><filename>binary-cache-url</filename></term> <listitem><para>A file containing the URL to a binary cache (such as <uri>https://cache.nixos.org</uri>). Nix will automatically check this cache for pre-built binaries, if the user has sufficient rights to add binary caches. For instance, in a multi-user Nix setup, the binary caches provided by the channels of the root user are used automatically, but caches corresponding to the channels of non-root users are ignored.</para></listitem> </varlistentry> </variablelist> </refsection> </refentry>