Next: , Previous: , Up: Utilities   [Contents][Index]

5.6 Invoking guix refresh

The primary audience of the guix refresh command is developers of the GNU software distribution. By default, it reports any packages provided by the distribution that are outdated compared to the latest upstream version, like this:

$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from to
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0

Alternately, one can specify packages to consider, in which case a warning is emitted for packages that lack an updater:

$ guix refresh coreutils guile guile-ssh
gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13

guix refresh browses the upstream repository of each package and determines the highest version number of the releases therein. The command knows how to update specific types of packages: GNU packages, ELPA packages, etc.—see the documentation for --type below. There are many packages, though, for which it lacks a method to determine whether a new upstream release is available. However, the mechanism is extensible, so feel free to get in touch with us to add a new method!

When passed --update, it modifies distribution source files to update the version numbers and source tarball hashes of those package recipes (see Defining Packages). This is achieved by downloading each package’s latest source tarball and its associated OpenPGP signature, authenticating the downloaded tarball against its signature using gpg, and finally computing its hash. When the public key used to sign the tarball is missing from the user’s keyring, an attempt is made to automatically retrieve it from a public key server; when this is successful, the key is added to the user’s keyring; otherwise, guix refresh reports an error.

The following options are supported:

-e expr

Consider the package expr evaluates to.

This is useful to precisely refer to a package, as in this example:

guix refresh -l -e '(@@ (gnu packages commencement) glibc-final)'

This command lists the dependents of the “final” libc (essentially all the packages.)


Update distribution source files (package recipes) in place. This is usually run from a checkout of the Guix source tree (see Running Guix Before It Is Installed):

$ ./pre-inst-env guix refresh -s non-core -u

See Defining Packages, for more information on package definitions.

-s subset

Select all the packages in subset, one of core or non-core.

The core subset refers to all the packages at the core of the distribution—i.e., packages that are used to build “everything else”. This includes GCC, libc, Binutils, Bash, etc. Usually, changing one of these packages in the distribution entails a rebuild of all the others. Thus, such updates are an inconvenience to users in terms of build time or bandwidth used to achieve the upgrade.

The non-core subset refers to the remaining packages. It is typically useful in cases where an update of the core packages would be inconvenient.

-m file

Select all the packages from the manifest in file. This is useful to check if any packages of the user manifest can be updated.

-t updater

Select only packages handled by updater (may be a comma-separated list of updaters). Currently, updater may be one of:


the updater for GNU packages;


the updater for GNOME packages;


the updater for KDE packages;


the updater for packages;

the updater for packages hosted on;


the updater for ELPA packages;


the updater for CRAN packages;


the updater for Bioconductor R packages;


the updater for CPAN packages;


the updater for PyPI packages.


the updater for RubyGems packages.


the updater for GitHub packages.


the updater for Hackage packages.


the updater for Stackage packages.


the updater for Crates packages.

For instance, the following command only checks for updates of Emacs packages hosted at and for updates of CRAN packages:

$ guix refresh --type=elpa,cran
gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9

In addition, guix refresh can be passed one or more package names, as in this example:

$ ./pre-inst-env guix refresh -u emacs idutils gcc@4.8

The command above specifically updates the emacs and idutils packages. The --select option would have no effect in this case.

When considering whether to upgrade a package, it is sometimes convenient to know which packages would be affected by the upgrade and should be checked for compatibility. For this the following option may be used when passing guix refresh one or more package names:


List available updaters and exit (see --type above.)

For each updater, display the fraction of packages it covers; at the end, display the fraction of packages covered by all these updaters.


List top-level dependent packages that would need to be rebuilt as a result of upgrading one or more packages.

See the reverse-package type of guix graph, for information on how to visualize the list of dependents of a package.

Be aware that the --list-dependent option only approximates the rebuilds that would be required as a result of an upgrade. More rebuilds might be required under some circumstances.

$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop@2.4.0 geiser@0.4 notmuch@0.18 mu@ cflow@1.4 idutils@4.6 …

The command above lists a set of packages that could be built to check for compatibility with an upgraded flex package.

The following options can be used to customize GnuPG operation:


Use command as the GnuPG 2.x command. command is searched for in $PATH.


Handle missing OpenPGP keys according to policy, which may be one of:


Always download missing OpenPGP keys from the key server, and add them to the user’s GnuPG keyring.


Never try to download missing OpenPGP keys. Instead just bail out.


When a package signed with an unknown OpenPGP key is encountered, ask the user whether to download it or not. This is the default behavior.


Use host as the OpenPGP key server when importing a public key.

The github updater uses the GitHub API to query for new releases. When used repeatedly e.g. when refreshing all packages, GitHub will eventually refuse to answer any further API requests. By default 60 API requests per hour are allowed, and a full refresh on all GitHub packages in Guix requires more than this. Authentication with GitHub through the use of an API token alleviates these limits. To use an API token, set the environment variable GUIX_GITHUB_TOKEN to a token procured from or otherwise.

Next: , Previous: , Up: Utilities   [Contents][Index]