Next: Substitutes, Previous: Features, Up: Package Management [Contents][Index]
guix package
The guix package
command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
previous configurations. It operates only on the user’s own profile,
and works with normal user privileges (see Features). Its syntax
is:
guix package options
Primarily, options specifies the operations to be performed during the transaction. Upon completion, a new profile is created, but previous generations of the profile remain available, should the user want to roll back.
For example, to remove lua
and install guile
and
guile-cairo
in a single transaction:
guix package -r lua -i guile guile-cairo
guix package
also supports a declarative approach
whereby the user specifies the exact set of packages to be available and
passes it via the --manifest option
(see --manifest).
For each user, a symlink to the user’s default profile is automatically
created in $HOME/.guix-profile. This symlink always points to the
current generation of the user’s default profile. Thus, users can add
$HOME/.guix-profile/bin to their PATH
environment
variable, and so on.
If you are not using the Guix System Distribution, consider adding the
following lines to your ~/.bash_profile (see Bash Startup
Files in The GNU Bash Reference Manual) so that newly-spawned
shells get all the right environment variable definitions:
GUIX_PROFILE="$HOME/.guix-profile" \ source "$HOME/.guix-profile/etc/profile"
In a multi-user setup, user profiles are stored in a place registered as
a garbage-collector root, which $HOME/.guix-profile points
to (see Invoking guix gc). That directory is normally
localstatedir/profiles/per-user/user
, where
localstatedir is the value passed to configure
as
--localstatedir
, and user is the user name. The
per-user directory is created when guix-daemon
is
started, and the user sub-directory is created by guix
package
.
The options can be among the following:
--install=package …
-i package …
Install the specified packages.
Each package may specify either a simple package name, such as
guile
, or a package name followed by a hyphen and version number,
such as guile-1.8.8
or simply guile-1.8
(in the latter
case, the newest version prefixed by 1.8
is selected.)
If no version number is specified, the
newest available version will be selected. In addition, package
may contain a colon, followed by the name of one of the outputs of the
package, as in gcc:doc
or binutils-2.22:lib
(see Packages with Multiple Outputs). Packages with a corresponding
name (and optionally version) are searched for among the GNU
distribution modules (see Package Modules).
Sometimes packages have propagated inputs: these are dependencies
that automatically get installed along with the required package
(see propagated-inputs
in
package
objects, for information about propagated inputs in
package definitions).
An example is the GNU MPC library: its C header files refer to those of the GNU MPFR library, which in turn refer to those of the GMP library. Thus, when installing MPC, the MPFR and GMP libraries also get installed in the profile; removing MPC also removes MPFR and GMP—unless they had also been explicitly installed independently.
Besides, packages sometimes rely on the definition of environment
variables for their search paths (see explanation of
--search-paths
below). Any missing or possibly incorrect
environment variable definitions are reported here.
Finally, when installing a GNU package, the tool reports the availability of a newer upstream version. In the future, it may provide the option of installing directly from the upstream version, even if that version is not yet in the distribution.
--install-from-expression=exp
-e exp
Install the package exp evaluates to.
exp must be a Scheme expression that evaluates to a
<package>
object. This option is notably useful to disambiguate
between same-named variants of a package, with expressions such as
(@ (gnu packages base) guile-final)
.
Note that this option installs the first output of the specified package, which may be insufficient when needing a specific output of a multiple-output package.
--install-from-file=file
-f file
Install the package that the code within file evaluates to.
As an example, file might contain a definition like this (see Defining Packages):
(use-modules (guix) (guix build-system gnu) (guix licenses)) (package (name "hello") (version "2.10") (source (origin (method url-fetch) (uri (string-append "mirror://gnu/hello/hello-" version ".tar.gz")) (sha256 (base32 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) (build-system gnu-build-system) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") (home-page "http://www.gnu.org/software/hello/") (license gpl3+))
Developers may find it useful to include such a package.scm file in the root of their project’s source tree that can be used to test development snapshots and create reproducible development environments (see Invoking guix environment).
--remove=package …
-r package …
Remove the specified packages.
As for --install
, each package may specify a version number
and/or output name in addition to the package name. For instance,
-r glibc:debug
would remove the debug
output of
glibc
.
--upgrade[=regexp …]
-u [regexp …]
Upgrade all the installed packages. If one or more regexps are
specified, upgrade only installed packages whose name matches a
regexp. Also see the --do-not-upgrade
option below.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
you should regularly run guix pull
(see Invoking guix pull).
--do-not-upgrade[=regexp …]
When used together with the --upgrade
option, do not
upgrade any packages whose name matches a regexp. For example, to
upgrade all packages in the current profile except those containing the
substring “emacs”:
$ guix package --upgrade . --do-not-upgrade emacs
--manifest=file
-m file
Create a new generation of the profile from the manifest object returned by the Scheme code in file.
This allows you to declare the profile’s contents rather than
constructing it through a sequence of --install
and similar
commands. The advantage is that file can be put under version
control, copied to different machines to reproduce the same profile, and
so on.
file must return a manifest object, which is roughly a list of packages:
(use-package-modules guile emacs) (packages->manifest (list emacs guile-2.0 ;; Use a specific package output. (list guile-2.0 "debug")))
--roll-back
Roll back to the previous generation of the profile—i.e., undo the last transaction.
When combined with options such as --install
, roll back occurs
before any other actions.
When rolling back from the first generation that actually contains installed packages, the profile is made to point to the zeroth generation, which contains no files apart from its own meta-data.
Installing, removing, or upgrading packages from a generation that has been rolled back to overwrites previous future generations. Thus, the history of a profile’s generations is always linear.
--switch-generation=pattern
-S pattern
Switch to a particular generation defined by pattern.
pattern may be either a generation number or a number prefixed
with “+” or “-”. The latter means: move forward/backward by a
specified number of generations. For example, if you want to return to
the latest generation after --roll-back
, use
--switch-generation=+1
.
The difference between --roll-back
and
--switch-generation=-1
is that --switch-generation
will
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
--search-paths[=kind]
Report environment variable definitions, in Bash syntax, that may be needed in order to use the set of installed packages. These environment variables are used to specify search paths for files used by some of the installed packages.
For example, GCC needs the CPATH
and LIBRARY_PATH
environment variables to be defined so it can look for headers and
libraries in the user’s profile (see Environment Variables in Using the GNU Compiler Collection (GCC)). If GCC and, say, the C
library are installed in the profile, then --search-paths
will
suggest setting these variables to profile/include
and
profile/lib
, respectively.
The typical use case is to define these environment variables in the shell:
$ eval `guix package --search-paths`
kind may be one of exact
, prefix
, or suffix
,
meaning that the returned environment variable definitions will either
be exact settings, or prefixes or suffixes of the current value of these
variables. When omitted, kind defaults to exact
.
--profile=profile
-p profile
Use profile instead of the user’s default profile.
--verbose
Produce verbose output. In particular, emit the environment’s build log on the standard error port.
--bootstrap
Use the bootstrap Guile to build the profile. This option is only useful to distribution developers.
In addition to these actions guix package
supports the
following options to query the current state of a profile, or the
availability of packages:
List the available packages whose name, synopsis, or description matches
regexp. Print all the meta-data of matching packages in
recutils
format (see GNU recutils databases in GNU recutils manual).
This allows specific fields to be extracted using the recsel
command, for instance:
$ guix package -s malloc | recsel -p name,version name: glibc version: 2.17 name: libgc version: 7.2alpha6
Similarly, to show the name of all the packages available under the terms of the GNU LGPL version 3:
$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' name: elfutils name: gmp …
Show details about package, taken from the list of available packages, in
recutils
format (see GNU recutils databases in GNU
recutils manual).
$ guix package --show=python | recsel -p name,version name: python version: 2.7.6 name: python version: 3.3.5
You may also specify the full name of a package to only get details about a specific version of it:
$ guix package --show=python-3.3.5 | recsel -p name,version name: python version: 3.3.5
List the currently installed packages in the specified profile, with the most recently installed packages shown last. When regexp is specified, list only installed packages whose name matches regexp.
For each installed package, print the following items, separated by
tabs: the package name, its version string, the part of the package that
is installed (for instance, out
for the default output,
include
for its headers, etc.), and the path of this package in
the store.
List packages currently available in the distribution for this system (see GNU Distribution). When regexp is specified, list only installed packages whose name matches regexp.
For each package, print the following items separated by tabs: its name, its version string, the parts of the package (see Packages with Multiple Outputs), and the source location of its definition.
Return a list of generations along with their creation dates; for each generation, show the installed packages, with the most recently installed packages shown last. Note that the zeroth generation is never shown.
For each installed package, print the following items, separated by tabs: the name of a package, its version string, the part of the package that is installed (see Packages with Multiple Outputs), and the location of this package in the store.
When pattern is used, the command returns only matching generations. Valid patterns include:
--list-generations=1
returns
the first one.
And --list-generations=1,8,2
outputs three generations in the
specified order. Neither spaces nor trailing commas are allowed.
--list-generations=2..9
prints the
specified generations and everything in between. Note that the start of
a range must be lesser than its end.
It is also possible to omit the endpoint. For example,
--list-generations=2..
, returns all generations starting from the
second one.
--list-generations=20d
lists generations
that are up to 20 days old.
When pattern is omitted, delete all generations except the current one.
This command accepts the same patterns as --list-generations.
When pattern is specified, delete the matching generations. When
pattern specifies a duration, generations older than the
specified duration match. For instance, --delete-generations=1m
deletes generations that are more than one month old.
If the current generation matches, it is not deleted. Also, the zeroth generation is never deleted.
Note that deleting generations prevents roll-back to them. Consequently, this command must be used with care.
Finally, since guix package
may actually start build
processes, it supports all the common build options that guix
build
supports (see common build options).
Next: Substitutes, Previous: Features, Up: Package Management [Contents][Index]