4 Getting Started

Presumably, you’ve reached this section because either you have installed Guix on top of another distribution (see Installation), or you’ve installed the standalone Guix System (see System Installation). It’s time for you to get started using Guix and this section aims to help you do that and give you a feel of what it’s like.

Guix is about installing software, so probably the first thing you’ll want to do is to actually look for software. Let’s say you’re looking for a text editor, you can run:

guix search text editor

This command shows you a number of matching packages, each time showing the package’s name, version, a description, and additional info. Once you’ve found out the one you want to use, let’s say Emacs (ah ha!), you can go ahead and install it (run this command as a regular user, no need for root privileges!):

guix install emacs

You’ve installed your first package, congrats! The package is now visible in your default profile, $HOME/.guix-profile—a profile is a directory containing installed packages. In the process, you’ve probably noticed that Guix downloaded pre-built binaries; or, if you explicitly chose to not use pre-built binaries, then probably Guix is still building software (see Substitutes, for more info).

Unless you’re using Guix System, the guix install command must have printed this hint:

hint: Consider setting the necessary environment variables by running:

     GUIX_PROFILE="$HOME/.guix-profile"
     . "$GUIX_PROFILE/etc/profile"

Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.

Indeed, you must now tell your shell where emacs and other programs installed with Guix are to be found. Pasting the two lines above will do just that: it will add $HOME/.guix-profile/bin—which is where the installed package is—to the PATH environment variable. You can paste these two lines in your shell so they take effect right away, but more importantly you should add them to ~/.bash_profile (or equivalent file if you do not use Bash) so that environment variables are set next time you spawn a shell. You only need to do this once and other search paths environment variables will be taken care of similarly—e.g., if you eventually install python and Python libraries, GUIX_PYTHONPATH will be defined.

You can go on installing packages at your will. To list installed packages, run:

guix package --list-installed

To remove a package, you would unsurprisingly run guix remove. A distinguishing feature is the ability to roll back any operation you made—installation, removal, upgrade—by simply typing:

guix package --roll-back

This is because each operation is in fact a transaction that creates a new generation. These generations and the difference between them can be displayed by running:

guix package --list-generations

Now you know the basics of package management!

Going further: See Package Management, for more about package management. You may like declarative package management with guix package --manifest, managing separate profiles with --profile, deleting old generations, collecting garbage, and other nifty features that will come in handy as you become more familiar with Guix. If you are a developer, see Development for additional tools. And if you’re curious, see Features, to peek under the hood.

Once you’ve installed a set of packages, you will want to periodically upgrade them to the latest and greatest version. To do that, you will first pull the latest revision of Guix and its package collection:

guix pull

The end result is a new guix command, under ~/.config/guix/current/bin. Unless you’re on Guix System, the first time you run guix pull, be sure to follow the hint that the command prints and, similar to what we saw above, paste these two lines in your terminal and .bash_profile:

GUIX_PROFILE="$HOME/.config/guix/current"
. "$GUIX_PROFILE/etc/profile"

You must also instruct your shell to point to this new guix:

hash guix

At this point, you’re running a brand new Guix. You can thus go ahead and actually upgrade all the packages you previously installed:

guix upgrade

As you run this command, you will see that binaries are downloaded (or perhaps some packages are built), and eventually you end up with the upgraded packages. Should one of these upgraded packages not be to your liking, remember you can always roll back!

You can display the exact revision of Guix you’re currently using by running:

guix describe

The information it displays is all it takes to reproduce the exact same Guix, be it at a different point in time or on a different machine.

Going further: See Invoking guix pull, for more information. See Channels, on how to specify additional channels to pull packages from, how to replicate Guix, and more. You may also find time-machine handy (see Invoking guix time-machine).

If you installed Guix System, one of the first things you’ll want to do is to upgrade your system. Once you’ve run guix pull to get the latest Guix, you can upgrade the system like this:

sudo guix system reconfigure /etc/config.scm

Upon completion, the system runs the latest versions of its software packages. When you eventually reboot, you’ll notice a sub-menu in the bootloader that reads “Old system generations”: it’s what allows you to boot an older generation of your system, should the latest generation be “broken” or otherwise unsatisfying. Just like for packages, you can always roll back to a previous generation of the whole system:

sudo guix system roll-back

There are many things you’ll probably want to tweak on your system: adding new user accounts, adding new system services, fiddling with the configuration of those services, etc. The system configuration is entirely described in the /etc/config.scm file. See Using the Configuration System, to learn how to change it.

Now you know enough to get started!

Resources: The rest of this manual provides a reference for all things Guix. Here are some additional resources you may find useful:

• See The GNU Guix Cookbook, for a list of “how-to” style of recipes for a variety of applications.
• The GNU Guix Reference Card lists in two pages most of the commands and options you’ll ever need.
• The web site contains instructional videos covering topics such as everyday use of Guix, how to get help, and how to become a contributor.
• See Documentation, to learn how to access documentation on your computer.

We hope you will enjoy Guix as much as the community enjoys building it!