Presumably, you’ve reached this section because either you have installed Guix on top of another distribution (veja Instalação), or you’ve installed the standalone Guix System (veja Instalação do sistema). 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 (veja Substitutos, 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
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: Veja Gerenciamento de pacote, 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, veja Desenvolvimento for additional tools. And if you’re curious, veja Recursos, 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: Veja Invocando
guix pull, for more information. Veja Canais, on how to specify additional channels to pull packages from, how to replicate Guix, and more. You may also find
time-machinehandy (veja Invoking
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. Veja Usando o sistema de configuração, 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:
- Veja 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.
- Veja Documentação, to learn how to access documentation on your computer.
We hope you will enjoy Guix as much as the community enjoys building it!