Manually Troubleshooting Portage

Portage is a layered system.

The most common interface which everyone using gentoo should be familiar with is emerge. It is the definitive command-line interface to the portage system1.

Sometimes, however, you are troubleshooting that one failing build, and the minute-long wait for portage to calculate dependencies is mostly a hazzle.


Portage ebuilds, and the corresponding ebuild comamnd, is used to build and install packages.

The sequence of commands that emerge runs is the following.

You as a user can run these manually, just find a package and replace the <ebuild> with the corresponding ebuild that you wish to install. This would cause the ebuild to be installed in the same manner as emerge would have done it, with the following exceptions.

Apart from this, the package would be installed on your system as usual.

You as a developer can now inspect each step for errors, and fix the problems you find.

If you decide that the ebuild has to be modified it’s equally straight forward.

#> mkdir -p $HOME/temp
#> cp -R /usr/portage/<category>/<package> $HOME/temp/<package>
... modify ebuild ...
#> sudo ebuild --skip-manifest <modified-ebuild> ...

This will cause ebuild to automatically configure a temporary overlay named X-<USER>.

If you later want to find these packages, use equery.

#> equery has repository x-<user>


Interacting with portage can feel daunting at first, but the steps you are taking are no different from the ones emerge itself uses when building your system.

That is the power of a layered system.

P.S. — You are of course still free to thoroughly shoot yourself in the foot, so be a bit careful!