Prologue: Why Guix?

It's 11 PM on a Sunday. You just ran a routine system update on your favorite Linux distro, and now your audio doesn't work.

You search online. Someone suggests reinstalling PulseAudio. Someone else says it's a kernel regression. A third person recommends switching to PipeWire. You try various combinations, editing config files you don't fully understand, copying commands from forum posts. Two hours later, sound works again, but you're not entirely sure what fixed it. And you have a nagging feeling you've introduced some other problem you haven't discovered yet.

Or maybe your story is different:

• You set up your development environment perfectly on your laptop, then spent a full day trying to recreate it on your desktop
• You want to try a new desktop environment, but you're afraid of breaking your current setup
• You inherited a server at work and have no idea what's installed on it or why
• You've been using Linux for years but still feel like you're fighting your system instead of working with it

These experiences have a common root cause: you don't truly understand or control your system. It works, mostly, but it's a black box that occasionally betrays you.

What if it didn't have to be this way?

Imagine a system where:

• Your entire configuration is readable code that you control
• Updates either succeed completely or don't happen at all (no half-broken states)
• If something goes wrong, you roll back in seconds and try again later
• Setting up a new machine is straightforward when your configuration is portable
• You can experiment freely, knowing you can always return to a working state
• Months from now, you can read your configuration and understand exactly what's installed and why

This isn't hypothetical. This is what using Guix feels like once you understand it.

The trade-off is real: Guix requires learning some new concepts. The configuration language will look unfamiliar at first. Some things that are "easy" on traditional distributions require more thought on Guix.

But here's what you get in return: a system you actually understand. Not a system you've managed to coerce into working, but one you've deliberately constructed and can reason about. When something goes wrong (and something always eventually goes wrong), you'll have the tools and knowledge to fix it confidently.

This course teaches you to use Guix as your daily operating system. By the end, you'll be able to:

• Read and write Guix system configurations
• Install Guix System on real hardware (including machines that need proprietary drivers)
• Find and install the software that you need
• Configure services like SSH, desktop environments, and more
• Update safely and roll back when needed
• Troubleshoot common issues using Guix's built-in tools
• Maintain your system with confidence over time

More importantly, you'll understand why Guix works the way it does. This conceptual foundation means you won't just be following recipes. You'll be able to solve problems we don't explicitly cover.

By the end of this course, you'll have:

1. A working Guix System configured to your preferences, running on real hardware
2. A configuration file you understand line-by-line, that you can version control and share with other people
3. The knowledge to maintain, update, and evolve your system on your own
4. A foundation for exploring Guix's more advanced features when you're ready

This course is designed for:

• Linux users who want more control and understanding of their system
• Developers who've heard about reproducible environments and want to apply the concept to their whole OS
• System administrators interested in declarative infrastructure
• Anyone frustrated with the complexity and fragility of traditional Linux system management

You don't need to be a Linux expert, but you should be comfortable with:

• Using the command line for basic tasks
• Editing text files
• General concepts like packages, services, and file systems

No prior Scheme or functional programming experience is required. I'll teach you exactly what you need to write and understand Guix configurations.

This course might not be for you if:

• You want a system that "just works" without understanding how. Guix may not be for you (yet!)
• You're not willing to invest time upfront to save time later
• You need specific proprietary software that isn't available on Guix (though with effort, most software can be made to work)

Guix rewards curiosity and patience. If you're the kind of person who wants to understand your tools, you'll feel right at home.

The course is organized into four parts:

We build your mental model of how Guix works: the store, profiles, generations, packages, services, and channels. You'll understand the "why" before the "how" so that everything we do next makes sense.

A hands-on walkthrough of installing Guix System on real hardware. We cover the use of a channel called Nonguix for hardware compatibility and getting your first working system.

Making the system your own. Finding packages, configuring services, and understanding best practices for system vs. user configuration.

Day-to-day maintenance: updating safely, rolling back when needed, and troubleshooting common issues.

Each section builds on the previous topics we cover. I recommend going through them in order, at least the first time so that you get a complete understanding of everything that we'll discuss.

In the System Crafters community, we believe in crafting your own computing experience which requires understanding the tools you use at a level deeper that most users.

It's easy to copy configuration snippets from the internet and hope they work. However it's harder, but far more valuable, to understand what those configurations do and why. When you understand your tools, you stop being at their mercy.

Guix embodies this philosophy. It's not the easiest Linux distribution to start with, but it might be the most rewarding to master. Every piece of your system is explicit, inspectable, and under your control.

This course won't just teach you to use Guix. It will teach you to think in Guix, to see your system as something you deliberately craft rather than something that happens to you.

Good news: you're not alone in this journey!

• The System Crafters community: Join us on IRC and the Forum to ask questions and share discoveries
• The Guix manual: Comprehensive reference documentation at guix.gnu.org
• The Guix mailing lists: Friendly community of Guix users and developers
• This course: Revisit sections as needed; they're designed as reference material also

Don't hesitate to ask for help. Both the Guix and System Crafters communities are welcoming to newcomers, and questions are how we all learn.

You're about to gain a fundamentally different relationship with your computer. The path requires some effort, but the destination is worth it: a system you truly understand and control.

Ready? Let's start with the fundamentals.