Next: , Previous: , Up: Package Management   [Contents][Index]

4.7 Channels

Guix and its package collection are updated by running guix pull (see Invoking guix pull). By default guix pull downloads and deploys Guix itself from the official GNU Guix repository. This can be customized by defining channels in the ~/.config/guix/channels.scm file. A channel specifies a URL and branch of a Git repository to be deployed, and guix pull can be instructed to pull from one or more channels. In other words, channels can be used to customize and to extend Guix, as we will see below.

4.7.1 Using a Custom Guix Channel

The channel called guix specifies where Guix itself—its command-line tools as well as its package collection—should be downloaded. For instance, suppose you want to update from your own copy of the Guix repository at, and specifically the super-hacks branch, you can write in ~/.config/guix/channels.scm this specification:

;; Tell 'guix pull' to use my own repo.
(list (channel
        (name 'guix)
        (url "")
        (branch "super-hacks")))

From there on, guix pull will fetch code from the super-hacks branch of the repository at

4.7.2 Specifying Additional Channels

You can also specify additional channels to pull from. Let’s say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the command line. You would first write modules containing those package definitions (see Package Modules), maintain them in a Git repository, and then you and anyone else can use it as an additional channel to get packages from. Neat, no?

Warning: Before you, dear user, shout—“woow this is soooo coool!”—and publish your personal channel to the world, we would like to share a few words of caution:

You’ve been warned! Having said this, we believe external channels are a practical way to exert your freedom to augment Guix’ package collection and to share your improvements, which are basic tenets of free software. Please email us at if you’d like to discuss this.

To use a channel, write ~/.config/guix/channels.scm to instruct guix pull to pull from it in addition to the default Guix channel(s):

;; Add my personal packages to those Guix provides.
(cons (channel
        (name 'my-personal-packages)
        (url ""))

Note that the snippet above is (as always!) Scheme code; we use cons to add a channel the list of channels that the variable %default-channels is bound to (see cons and lists in GNU Guile Reference Manual). With this file in place, guix pull builds not only Guix but also the package modules from your own repository. The result in ~/.config/guix/current is the union of Guix with your own package modules:

$ guix pull --list-generations
Generation 19	Aug 27 2018 16:20:48
  guix d894ab8
    repository URL:
    branch: master
    commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
  my-personal-packages dd3df5e
    repository URL:
    branch: master
    commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
  11 new packages: my-gimp, my-emacs-with-cool-features, …
  4 packages upgraded: emacs-racket-mode@0.0.2-2.1b78827, …

The output of guix pull above shows that Generation 19 includes both Guix and packages from the my-personal-packages channel. Among the new and upgraded packages that are listed, some like my-gimp and my-emacs-with-cool-features might come from my-personal-packages, while others come from the Guix default channel.

To create a channel, create a Git repository containing your own package modules and make it available. The repository can contain anything, but a useful channel will contain Guile modules that export packages. Once you start using a channel, Guix will behave as if the root directory of that channel’s Git repository has been added to the Guile load path (see Load Paths in GNU Guile Reference Manual). For example, if your channel contains a file at my-packages/my-tools.scm that defines a Guile module, then the module will be available under the name (my-packages my-tools), and you will be able to use it like any other module (see Modules in GNU Guile Reference Manual).

4.7.3 Declaring Channel Dependencies

Channel authors may decide to augment a package collection provided by other channels. They can declare their channel to be dependent on other channels in a meta-data file .guix-channel, which is to be placed in the root of the channel repository.

The meta-data file should contain a simple S-expression like this:

 (version 0)
   (name some-collection)
   (url ""))
   (name some-other-collection)
   (url "")
   (branch "testing"))))

In the above example this channel is declared to depend on two other channels, which will both be fetched automatically. The modules provided by the channel will be compiled in an environment where the modules of all these declared channels are available.

For the sake of reliability and maintainability, you should avoid dependencies on channels that you don’t control, and you should aim to keep the number of dependencies to a minimum.

4.7.4 Package Modules in a Sub-directory

As a channel author, you may want to keep your channel modules in a sub-directory. If your modules are in the sub-directory guix, you must add a meta-data file .guix-channel that contains:

  (version 0)
  (directory "guix"))

4.7.5 Writing Channel News

Channel authors may occasionally want to communicate to their users information about important changes in the channel. You’d send them all an email, but that’s not convenient.

Instead, channels can provide a news file; when the channel users run guix pull, that news file is automatically read and guix pull --news can display the announcements that correspond to the new commits that have been pulled, if any.

To do that, channel authors must first declare the name of the news file in their .guix-channel file:

  (version 0)
  (news-file "etc/news.txt"))

The news file itself, etc/news.txt in this example, must look something like this:

  (version 0)
  (entry (tag "the-bug-fix")
         (title (en "Fixed terrible bug")
                (fr "Oh la la"))
         (body (en "@emph{Good news}!  It's fixed!")
               (eo "Certe ĝi pli bone funkcias nun!")))
  (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
         (title (en "Added a great package")
                (ca "Què vol dir guix?"))
         (body (en "Don't miss the @code{hello} package!"))))

The file consists of a list of news entries. Each entry is associated with a commit or tag: it describes changes made in this commit, possibly in preceding commits as well. Users see entries only the first time they obtain the commit the entry refers to.

The title field should be a one-line summary while body can be arbitrarily long, and both can contain Texinfo markup (see Overview in GNU Texinfo). Both the title and body are a list of language tag/message tuples, which allows guix pull to display news in the language that corresponds to the user’s locale.

If you want to translate news using a gettext-based workflow, you can extract translatable strings with xgettext (see xgettext Invocation in GNU Gettext Utilities). For example, assuming you write news entries in English first, the command below creates a PO file containing the strings to translate:

xgettext -o news.po -l scheme -ken etc/news.scm

To sum up, yes, you could use your channel as a blog. But beware, this is not quite what your users might expect.

4.7.6 Replicating Guix

The guix pull --list-generations output above shows precisely which commits were used to build this instance of Guix. We can thus replicate it, say, on another machine, by providing a channel specification in ~/.config/guix/channels.scm that is “pinned” to these commits:

;; Deploy specific commits of my channels of interest.
(list (channel
       (name 'guix)
       (url "")
       (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
       (name 'my-personal-packages)
       (url "")
       (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))

The guix describe --format=channels command can even generate this list of channels directly (see Invoking guix describe). The resulting file can be used with the -C options of guix pull (see Invoking guix pull) or guix time-machine (see Invoking guix time-machine).

At this point the two machines run the exact same Guix, with access to the exact same packages. The output of guix build gimp on one machine will be exactly the same, bit for bit, as the output of the same command on the other machine. It also means both machines have access to all the source code of Guix and, transitively, to all the source code of every package it defines.

This gives you super powers, allowing you to track the provenance of binary artifacts with very fine grain, and to reproduce software environments at will—some sort of “meta reproducibility” capabilities, if you will. See Inferiors, for another way to take advantage of these super powers.

Next: , Previous: , Up: Package Management   [Contents][Index]