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
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
python and Python libraries,
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
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:
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
At this point, you’re running a brand new Guix. You can thus go ahead and actually upgrade all the packages you previously installed:
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:
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-machinehandy (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!