Fix my Gentoo

From Gentoo Wiki
Jump to:navigation Jump to:search

This guide is something I've posted on the forums several times in response to users posting that "nothing works". If gcc is broken after a --depclean, this guide is not for you. You almost certainly need gcc-config. Be more careful in future.

This guide is for rescuing your install when you can't chroot in, almost nothing seems to work but you have determined that you need some binary packages to fix your system.

It is actually very difficult to break Gentoo so badly, it can't be fixed.


You need some binary packages to fix your Gentoo.

You might find them on a binhost or tinderbox on the web but they are unlikely to be built for your system, with your USE flags and your CFLAGS.

This guide shows you how to make your own binary packages to use to fix your own system. You will not need another system, a spare partition or even another install.

  • A working internet connection.
  • A way to boot your broken box with some recovery media, e.g. System Rescue CD, if it won't boot
  • About 20G of free space on your broken install. 5G may do, depending on what you need to build.


As the bootable install is not working and we need a working install to build binary packages, we need another install (just an extracted stage3 somewhere). This install need not be bootable.

It is sufficient to be able to chroot into it and run emerge. This rescue install will share some elements with the broken install which saves space and makes things easier in the final steps.

Getting started


  • /mnt/gentoo: Mount your own broken install here.
  • /mnt/gentoo/home/rescue: The new rescue install, it can be anywhere but it needs to be on a hard disk.

The rescue install

  • Mount your broken install at /mnt/gentoo so we can use its hard drive space and its /var/db/repos/gentoo.
  • Make a directory at /mnt/gentoo/home/rescue or somewhere with free space:
root #mkdir /mnt/gentoo/home/rescue
  • Follow the handbook to fetch a stage3 tarball and untar it to /mnt/gentoo/home/rescue.
  • Do not get a Portage snapshot, we will use the one in the main install.
  • Follow the handbook for all the odds and ends, like copying /etc/resolv.conf


  • Mount /dev and friends in /mnt/gentoo/home/rescue just as if you were doing a new install but do not chroot yet.
  • Bind mount the ebuilds to the rescue system:
root #mount -o bind /mnt/gentoo/var/db/repos/gentoo /mnt/gentoo/home/rescue/var/db/repos/gentoo
  • Bind mount the distfiles directory:
root #mount -o bind /mnt/gentoo/var/cache/distfiles /mnt/gentoo/home/rescue/var/cache/distfiles
  • Bind mount the binary package directory:
root #mount -o bind /mnt/gentoo/var/cache/binpkgs /mnt/gentoo/home/rescue/var/cache/binpkgs
  • Copy over /mnt/gentoo/etc/portage to /mnt/home/rescue/etc/portage
root #cp -r /mnt/gentoo/etc/portage /mnt/gentoo/home/rescue/etc/portage

Now the rescue install has all your own settings too.

Chroot in to rescue install

Follow what the handbook says but into /mnt/gentoo/home/rescue.

Edit /etc/portage/make.conf

Inside of the new working rescue chroot, we need to tell Portage to create and save binary packages of everything we build.

Edit /etc/portage/make.conf by adding buildpkg to FEATURES.

This causes Portage to save binary tarballs of every package built to /var/cache/binpkgs.

Do not emerge --sync. You need packages that match your installed system which requires the repository to be in the same state.

Building packages

Two choices:

  1. quickpkg
  2. emerge

Quick package (quickpkg)

Take care with quickpkg, it either drops configuration files or copies them in their current state from the install. This may be undesirable.

If the package needed is part of the stage3, use the quickpkg tool to make a binary package.


emerge will just work. Build something small as a test like sys-apps/sed then check that the package has appeared in /var/cache/binpkgs.

More packages

emerge whatever is needed. /home/rescue will stay around until deleted and it is only a chroot away. Upon return, don't forget to redo the bind mounts.

Installing binary packages

After creating binary packages using any of the methods described above, they must be installed somehow to the broken system.

The best method to install binary packages depends on what is broken. The options below are presented in increasing order of risk (least risky first):

  1. Install "properly" using emerge where it works.
  2. Raw extract with tar the binpkgs (tarballs) onto the broken system until you can do the safer option.

Using emerge

This requires that you can chroot into the install to be rescued. If you have managed to remove a part of your toolchain, this should work for you.

root #emerge -K <package/atom>

This will either install the binary tarball and its dependencies or fail if the binaries cannot be found.

Using tar

So you can't chroot in, emerge is not an option. Maybe you removed sys-libs/glibc and you don't have a statically linked sys-apps/busybox?

Each binary package is like a single package stage3. It has some extra information on the end that Portage uses, which will provoke a warning from tar that can be safely ignored.

There is no safety net, tar will just spray files all over your filesystem.

Extracting tar step-by-step method

For safety's sake, unmount the rescue install at /mnt/gentoo/home/rescue.

root #umount /mnt/gentoo/home/rescue

You may need to unmount all the things mounted inside /mnt/gentoo/home/rescue first.

Sanity checks

Before you issue the tar command, verify:

  • The install is mounted at /mnt/gentoo
  • You understand the -xpf and -C options to tar. Review the man page if unsure:
root #man tar
Understanding the tar command
The -p option is essential. Without it, tar will work, the files will be installed but execute permissions will be dropped.
Check the destination path: -C /mnt/gentoo, this is where all the output files will be sent.
tar will work out the compression for itself, so the -j option is not required.
root #tar --xattrs -xpf /mnt/gentoo/var/cache/binpkgs/<package/atom> -C /mnt/gentoo

This tells tar to extract, preserving permissions, the file /mnt/gentoo/var/cache/binpkgs/<package/atom> and Change directory to /mnt/gentoo before it does anything else.

In fact, the input file name above is not correct. The full path to the tarball is required. Tab completion helps a lot.

Nervous users can add the -v option to tar.


As described above, unpack the tarball (binary package) into your broken system.

root #tar --xattrs -xpf /mnt/gentoo/var/cache/binpkgs/<package/atom> -C /mnt/gentoo

The package is now effectively installed to the broken install. Repeat as necessary for all packages until you can use emerge (see above) instead.

Tidying up

Once the damage is fixed, delete /home/rescue, or keep it around for next time.

With adequate space, it may be desirable to add buildpkg to your FEATURES as a regular thing. Then, the tarballs needed for rescuing your system will already exist.

Both /var/cache/distfiles and /var/cache/binpkgs will grow without limit. Run eclean occasionally to prune them.

See also

Project:Portage/Fixing broken portage — provides guidance on how to manually update or fix a broken Portage installation - particularly in the event emerge -v1 sys-apps/portage cannot be run.