Installing and using gentoo linuxIf you ask around about Gentoo, chances are you will get mixed reviews : some will say it's a waste of time, others will say it's only for ubergeeks, yet others will tell you it's the only way, but no one can deny the power that Gentoo offers in terms of choices and speed. Gentoo is a rolling release distribution, which means it has no release numbers and it's updated continuously.Gentoo is also a source-based distribution, which means that everything you install you must compile first. What Gentoo is not : it certainly isn't for everyone. If you prefer the comfort of binary package managers that install desired software on-the-fly, if you like to install your distro in an hour or so, then you might not like Gentoo. That being said, if you're curious, aren't afraid of the command line and some compilation, if you want to have your system just the way you want it or you just want to be more 1337, this article is just what you need. You will learn how to install, what to install, how to get the most out of your system and of course have some fun in the process. We must warn you before we start : Gentoo has some of the best written documentation of all the Linux distributions and this article cannot and does not want to take its place, by no means. Although you will have a working Gentoo system after going through our tutorial, you are advised to read the handbook and all other sections of general interest, like Portage (the software management tool), for example. That said, let's get ready and start installing Gentoo.

Getting and installing Gentoo

Fetching the iso image

Gentoo is mirrored in many locations, so we suggest you pick one mirror close to you and start downloading. We always trust Heanet, so we got our ISO from there. Since Gentoo is a rolling release distro, it offers new iso images periodically. The mirror layout might differ, but the Gentoo directory layout is standard : releases/$arch/current-iso/. On our system, we chose amd64 as $arch, but Gentoo offers installation images for more hardware architectures than most distributions, a notable exception being Debian. After you write the image, we're ready to go further.

Booting and prerequisites

Gentoo's hardware requirements are small, compared to other distros. However, keep in mind that you will compile some big pieces of software like the kernel, which take some time. Here there's an advantage and a disadvantage : if you use Gentoo on an older machine, it will take longer (days, maybe) to have it up and running just the way you want it. The upside is, you only install once and then you have a distro tailored to your hardware, so you can squeeze every bit out of it. Again, there are split opinions about this approach, so we will let you decide. If you have some modern piece of hardware, of course you won't have this problem. Before we begin, we'll like to ask you to make a list of your hardware : you will have to compile your own kernel so you'll have to know your machine pretty well.

Now let's boot from the CD. At the first prompt, press Enter so you can boot the default kernel. Should have special hardware needs, refer to the Handbook for a list of options.


Next, we will need a working Internet connection, so we must set it up if it isn't already. If you connect to the Internet by DHCP, chances are you're already set. Use ping to make sure it is so. If not, use ifconfig first to see if your Ethernet card is present:

 # ifconfig -a 

You should see eth0 (or eth1, eth2, depending on how many NICs you have) listed. If not, the driver for your card wasn't automatically loaded at boot or your card isn't supported. Use modprobe to insert the correct module, as we presume you know your hadware, as specified below:

 # modprobe forcedeth 

This is just an example for a nForce Ethernet card. After you see your card listed in ifconfig's output, use

 # dhcpcd eth0 

for DHCP or ifconfig for fixed IP. Gentoo also offers net-setup, which is an interactive script that can be used like

 # net-setup eth0 

Alright, now that you have a working Internet connection, let's continue with disk partitioning.


We are not going to walk you through every step necessary to partition your disk. Instead, we will give you some pointers which will be useful to get your setup right. You can use fdisk for a pure command-line based interface or cfdisk for a curses-based one. If you already have your system drive partitioned, you can skip this step.

Before we start explaining (c)fdisk, we should stop for a while and see how you should partition and why. As Grand Master Yoda would say "You must un-learn what you have learned", because the partitioning setup for a source-based distro isn't (always) the same as the partitioning setup for a binary distro. Why? One intermediary step between source code and the executable is the creation of object files which are then linked into the final result. These object files tend to take some space, together with other compilation-specific ones. Hence we recommend a simple layout, as a Gentoo beginner, with / having plenty of space and swap according to the physical memory installed.


Invoke fdisk with the drive you want to set up like so :

 # fdisk /dev/sda 

We will assume the creation of two partitions, as stated before. fdisk's commands are single letter and intuitive : a adds a partition, d deletes, p prints and so on. Use n (for new partition) with t to set the partition type (83 for / and 82 for swap) and q if you want to quit without writing the changes. Again, refer to the Handbook for all the gory details, but in the end, with these commands, you're set. Remember to make / bootable with 'a', of course. Using w will write your changes.


With cfdisk, it's a shorter story since you get a nice curses-based menu with the partitions in the upper side and the commands you can use in the lower side. Just remember to mark the / partition bootable and set the partition types correctly : 83 and 82, as above.

Creating filesystems

In order to have a filesystem on our newly created partitions, we must run mkfs.$type $partition or mkswap $partition for swap.

 # mkfs.ext3 /dev/sda1 
 # mkswap /dev/sda2 

You can replace the ext3 part with ext2, ext4, jfs or xfs, but we consider ext3 to be a sensible choice for the root partition. Now let's make use of what we just created :

 # swapon /dev/sda2 
 # mount /dev/sda1 /mnt/gentoo 

Installing a stage

A stage, in Gentoo terminology, is an archive that will give you a working base to go on from. In the past, there were three stages supported : stage 1, stage 2 and stage 3 (see link). At the moment, only stage 3 installation is supported, which doesn't require bootstrapping the system, since that's done already in our scenario. Before that, you must make sure that your date is set properly, then, using links, get the latest stage 3 tarball (again, we will use Heanet as an example, but if you want to use a different mirror:

 # cd /mnt/gentoo 
 # links 

Find the file stage3-amd64-20110922.tar.bz2 (the date will probably differ, as you can see from the screenshot), put the cursor on it, press 'd' (download) and press enter. Exit the browser with 'q'. Now we must unpack the stage (make sure you are in /mnt/gentoo and you type the command exactly as shown):

 # tar xvjpf stage3-*.tar.bz2 

The tar flags are : x for extract, v for verbose, j to tell tar it's a bzip2 archive, p to preserve permissions (very important!) and f to say that the argument is a file, not a stream. If you look at the lines scrolling on your screen while unpacking, you will notice that stage 3 is nothing else but a "skeleton" of a working system's directory structure.

Downloading gentoo release

Installing Portage

We will explain more later about Portage in greater detail, but for now, the idea is as follows : the Portage archive you're about to download and extract is mostly everything you will need to install software on a Gentoo system. Portage was inspired by FreeBSD's ports system, hence the name, so if you ever worked with ports/pkgsrc on BSD systems, this will sound very familiar. Again, use links to go to the mirrors list, choose one and get the latest portage tree. On our system, we did

 # links 

and got the portage-latest.tar.bz2 file, then unpacked it (we are still in /mnt/gentoo, of course, but we will use absolute paths just to be sure) :

 # tar xvjf /mnt/gentoo/portage-latest.tar.bz2 -C /mnt/gentoo/usr 

Configuring compilation options

Now, after all this setting up and unpacking, it's time we start configuring the system to fit our hardware. The file we need to edit is /mnt/gentoo/etc/make.conf in order to set some sensible options fit for our hardware. Our example system is a 64-bit Athlon, so we will add -march=k8 to CFLAGS. Ok, take it easy, we haven't started speaking alien language. CFLAGS is an environment variable that gcc, the compiler, takes in consideration when building software. So when adding something to CFLAGS, consider that every compilation ever made on your system will have that flag passed onto gcc. Hence, one must be very careful not to over-optimize or set flags just for setting's sake : use something appropriate for your CPU. So, -march stands for "machine architecture" and tells gcc to optimize the code it generates for that particular CPU type. On our Gentoo system, that's the only thing we added to CFLAGS, leaving the other existing options as they were. Read the gcc manual for options sensible to your hardware. You might wanna set MKFLAGS, which are flags passed to make, to -jx, where x is the name of CPU cores plus one. The Gentoo Live CD offers nano as an editor, so we will use that to enter the aforementioned changes :

 # nano -w /mnt/gentoo/etc/make.conf 

Final preparations and chroot

Before chrooting in our new environment so we can start installing Gentoo, there are few things left to do. First is setting a mirror for software downloads in make.conf. No, this you don't have to do by hand : Gentoo offers you the utility called mirrorselect, which we will use to set up a "normal" mirror (http, ftp) and a rsync one. The commands are (beware to use '>>' and NOT '>'):

 # mirrorselect -i -o >> /mnt/gentoo/etc/make.conf 
 # mirrorselect -i -r -o >> /mnt/gentoo/etc/make.conf 

You will, of course, want networking to be available in your new environment, so you must copy DNS-related information :

 # cp -L /etc/resolv.conf /mnt/gentoo/etc/ 

Finally, we will need to make the proc and dev filesystems available to the new system and we're ready:

 # mount -t proc none /mnt/gentoo/proc 
 # mount --rbind /dev /mnt/gentoo/dev 

We are assuming that you know what a chroot is and we insist on reading about the command you're about to type instead of typing it blindly. It will not help you learn anything and you have better chances of hosing your system. Linux and Gentoo in special is about learning, and we hope you like what you are doing.

After this short intermezzo, we can finally chroot in our new environment :

 # chroot /mnt/gentoo /bin/bash 
 # env-update 
 # source /etc/profile 
 # export PS1="(chroot) $PS1" 

USE flags

It is now time we update our portage tree so we can install software as needed in preparation of our final installation.

 # emerge --sync 

After the update finishes, we get to a very important part that's necessary when configuring a Gentoo system : USE flags. This is something unique to Gentoo and a means to customize your system to fit your exact needs. We feel an introduction is in order, so please read this carefully. You are expected to know exactly what do you want your system to be : if you want a desktop, will you run KDE or KDE-based apps or GNOME and GTK-based ones, or maybe neither, just, say, Fluxbox? Do you want a server? What services will it provide? We urge you to think this through, since it will save you a lot of hassle later. USE flags, as one can infer from the name, are keywords inserted in make.conf in order to tell Portage what capabilities you want your system to offer. Perhaps an example will be more appropriate in order to help you understand the power and importance of USE flags. Let's say you want to have a KDE-based desktop/workstation. You add kde and qt4 to the list of USE flags so any application you install that offers KDE support will add that capability at configuration time. If you don't want GTK support in your installed applications (those that support it), you just add a '-' sign in front of the gtk and gnome flags and you're set. The complete list of possible USE flags are to be found at /usr/portage/profiles/use.desc . Browse through the file and make sure you set USE flags appropriate for the purpose. A word of warning, though : if your list of USE flags is too short, chances are some applications you will install will ask you to enable some lacking flags, which you can do globally in make.conf or per package in /etc/portage/package.use. On the other hand, should you overuse the USE options, you will compile lots of (possibly) unnecessary software. That's why it's better to sit and think things through before writing the USE flags. More on this later. Now, after deciding what is it exactly we do want, open /etc/make.conf and add USE flags like so (chances are there are a few already there) :

 USE="acpi apm ..." 

Save the file and get ready for another important part : kernel configuration.

Kernel configuration

This part is going to be shorter than one might expect, for two reasons : one, we already wrote an article on the subject, and that covers most of what you need, second, when you type 'make menuconfig' you will already have a minimalist configuration suited for your hardware, but that won't mean you aren't encouraged to tweak more. Also, Gentoo offers genkernel, a kernel that is resemblant to the kernel on the live CD, but we won't cover that here : if we start tweaking, it would be a pity to leave the kernel out of this. Before we go into the kernel configuration step, though, we must select our system's timezone. Timezones information is stored in /usr/share/zoneinfo, so we need to copy the appropriate zoneinfo file to /etc/localtime :

 # cp /usr/share/zoneinfo/Europe/Bucharest /etc/localtime 

Change Europe/Bucharest to your location and you're ready to get the kernel source :

 # emerge gentoo-sources 

Yes, this is how one installs software on Gentoo : emerge $package. Not that complicated, is it? Of course, there are various options to the emerge command, making it a versatile package manager. Use the manual page to see the options and what they do, as you will use emerge a lot as a Gentoo user.

After the kernel sources are downloaded, you will see in /usr/src a symlink named linux which points to the actual kernel sources folder, like linux-2.6.39-gentoo-r3 (the latest stable version at the time of this writing). So, as per our previous article's indications, just type

 # cd /usr/src/linux 
 # make menuconfig 

Take your time to configure your kernel carefully according to your hardware, then build and install :

 # make && make modules_install 

This will take some time, depending on the options and the hardware. Remember you don't have to add -jn to make, because it's set in make.conf. We can now copy the kernel to /boot :

 # cp arch/x86_64/boot/bzImage /boot/kernel-2.6.39-gentoo-r3 

It's better if you write down the exact name of your kernel, you'll need it later. If you need some kernel module autoloaded, get its' name from /lib/modules and add it to /etc/conf.d/modules. For more details, consult the Gentoo Handbook.


The file's name stands for FileSystem TABle and it lists filesystems to mount automatically at boot, their mount points and options. It's a crucial file on any Linux/Unix system, so we recommend extra care when editing it. When opening it, you will see it already has some entries you can use as a starting point, like /dev/ROOT or /dev/SWAP. Replace ROOT with sda1 and SWAP with sda2, as per our example, check mount points and options, save and exit. The fstab file has a simple syntax of the form

# This is a commented example :
#/dev/sda3 /var ext3 noatime 0 0

The last three parts refer to mount options, dump options and filesystem check order. Refer to the fstab manual for further details, as this will be useful anywhere, not only on Gentoo and not only on Linux, for that matter. Double check the file, save and continue to

Networking information and configuration

Yes, you've already done that, but that was only for the installation. This time it is permanent, for your installed system. So, we will need to set the hostname (/etc/conf.d/hostname), domain name (/etc/conf.d/net) and configuration of the network per se.

 # echo "config_eth0=\"dhcp\"" >> /etc/conf.d/net 

Add localhost to /etc/hosts, as well as any other hosts you might need, then set the network to be autostarted at boot :

# cd /etc/init.d
# ln -s net.lo net.eth0
# rc-update add net.eth0 default

System configuration and system tools

You may have noticed we haven't done something essential yet : setting root's password. It's time we do it now:

 # passwd 

Let's edit /etc/conf.d/hwclock in order to make sure we tell the system how is our hardware clock set. If you have it set at local time, as many systems have, use


There are some system tools you find installed on every "normal" Linux installation and take for granted, but remember? Gentoo is all about customization and choice. So we'll have to install a syslogger and a cron daemon. The Handbook recommends syslog-ng and vixie-cron for those purposes, so we'll go with that :

 # emerge syslog-ng vixie-cron 

If you were careful, we added the network service to be started at boot with rc-update. Use the same syntax to add syslog and cron, as these are services essential to any Linux system. The general syntax is

 # rc-update add $service default 

"default" refers to the default runlevel, as per /etc/inittab. Now, as we worked with a DHCP configuration throughout the installation, we want to use it on our installed system as well, so we use

 # emerge dhcpcd 

There are some of you that might have noticed that something else, very important, is still missing from our future system : a bootloader. In the following section we will use GRUB as the example, but you can use LILO as well, although we only cover GRUB here. After emerging GRUB, we need to edit its' config file in /boot/grub/grub.conf in order to let it know about our kernel. We will show you how our grub.conf file looks like, then explain every section.

default 0
timeout 20

# use the branding USE flag for a nice Gentoo splash
title Gentoo Linux 2.6.39-r3
kernel /boot/kernel-2.6.39-gentoo-r3 root=/dev/sda1

gentoo grub

GRUB starts numbering from 0, not from 1 as you might expect, so be extra careful. Basically, if you followed our advice about partitioning, your grub.conf should look the same, unless the kernel version differs. So, default=0 means that the default kernel to be loaded when the 20 second timeout expires will be the first one (top to bottom). splashimage is the file that'll make your GRUB screen look more pleasant, and of course you can download and use any splash image for GRUB your heart desires. "title" is what you'll see when your system boots and "root(hd0,0)" tells GRUB the location of the boot image in terms it understands. The last line is self-explanatory, we think. Check and double-check the grub.conf file and then save it.

Since we are in a chrooted filesystem, we need a /etc/mtab file, which lists the mounted filesystems. This command creates it :

 # grep -v rootfs /proc/mounts > /etc/mtab 

Now all we have to do, after checking /boot/grub/grub.conf and /etc/mtab, is to install GRUB :

 # grub-install /dev/sda 

Using /dev/sda (without a partition number, like sda2) will tell grub to install itself in the MBR of the first disk.


Congratulations! If you stayed with us and didn't already rebooted to some other, easier to use distribution, it probably means you have a Gentoo system installed! After you will reboot gracefully, you will see your Gentoo Linux root prompt, waiting for your commands. Where to go from here? We will show you briefly. But first, let's go back to the "reboot gracefully" part :

# exit
# cd
# umount -l /mnt/gentoo/dev{/shm,/pts,}
# umount -l /mnt/gentoo{/boot,/proc,}
# reboot

Using your Gentoo system

Adding a user

We don't recommend issuing commands as root except when it's needed, since that's an invitation to disaster. Create a user, install sudo and your editor of choice and add your user to sudoers group:

# useradd -m -G wheel $user
# emerge sudo $editor
# visudo


You now have a very basic system installed, so the first thing you do is install some software. The most used things users expect from a software manager is search, install, update and remove. This is what this section will deal with.


For the sake of example, let's say you want to install mplayer. But there are a lot of mplayer-related packages (Gentoo has lots of software to offer!), so you don't know exactly what options you do have. Using

 $ emerge --search mplayer | less

will help you decide.


As you have seen earlier, "emerge $package" is the way to go for installation. There are lots of options to use when installing, but we will only deal with --pretend, which only shows you what would be installed, but does not go through the actual installation. Since you're new with the concept of USE flags and you want to see how they influence the installation of new software, use

 # emerge --pretend mplayer 

which, as you'll see, will help you a lot deciding what USE flag you need to add and remove, globally or per-package.

Updating and upgrading

We told you earlier about "emerge --sync" to update the Portage tree. But how to upgrade installed software? What if you changed some USE flags in the meantime? How will that affect the other packages? A everyday-use command would be

 # emerge --update --deep --newuse world 

The first flag is obvious. --deep takes care of dependencies, so we suggest you use it every time, and --newuse is useful if some USE flags have been altered since the last update.

Removing software

You realized you installed something you don't really need. In our example, maybe you want to use VLC instead of mplayer, so you want to get rid of the latter. Since installation is called emerging in Gentoo terminology, the option to uninstall is, you guessed it, --unmerge. So, in order to uninstall mplayer and install vlc, one would do

 # emerge --unmerge mplayer && emerge vlc 

But mplayer pulled some dependencies when it got installed, and we don't need them anymore. emerge's --depclean flag helps you locate unneeded dependencies. Be forewarned, though : emerge will not tell you if what you remove is needed by some other piece of software, except system-essential software like glibc. So think twice before unmerging, we say.

Other Portage subjects

As you'll see in the Handbook, there are a lot (and we mean that) of subjects related to Portage we haven't covered here, for the sake of brevity : masked packages, software categories, overlays, etc. Either you wait until you'll have to deal with them, either (the preferred and recommended way) you start reading so at least you have an idea of the grand scheme of things.

Further reading

As we said and repeated, what you have read here is a small part of what Gentoo means. We only thought that the Handbook is a little dry and wanted to make it a little more palatable for the user wanting to learn. Instead of handing out links and books, we'll stick to saying this : read the Handbook, then read it again, then read the manual pages when needed, then use the links from the Handbook to go to other Gentoo tutorials and, most important, use Gentoo. Have lots of fun with it, too.