3.2 Invoking 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 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.

In a multi-user setup, user profiles must be 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. It must be created by root, with user as the owner. When it does not exist, guix-package emits an error about it.

The options can be among the following:

--install=package

-i package

Install package.

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

--remove=package

-r package

Remove package.

--upgrade=regexp

-u regexp

Upgrade all the installed packages matching regexp.

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

--profile=profile

-p profile

Use profile instead of the user's default profile.

--dry-run

-n

Show what would be done without actually doing it.

--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-installed[=regexp]

-I [regexp]

List currently installed packages in the specified profile. 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-available[=regexp]

-A [regexp]

List packages currently available in the software distribution (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 (out for the main files, lib for libraries and possibly headers, etc.), and the source location of its definition.