Project:Portage/Fixing broken portage

This article 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. While not hard it is still to be done with great care, so please follow the listed steps a closely as possible, but apply common sense when necessary.

Modern guidance

Warning
If only Python 2.7 is installed, leap-frogging will be required by using portage-2.3.103, which is the last version to support Python 2.

In emergencies, it is possible to run Portage directly from an extracted tarball. This is often required if it's not possible to run the current version of Portage to emerge packages at all. This advice is based on the testing Portage tips for developers.

Fetch Portage:

Go to portage.git and download the latest tarball from the tags/download section. At time of writing, this is Portage 3.0.28.

Extract the tarball:

root #mkdir -p /tmp/portage && cd /tmp/portage

root #wget https://gitweb.gentoo.org/proj/portage.git/snapshot/portage-3.0.28.tar.gz

root #tar xvf portage-3.0.28.tar.gz -C /tmp/portage --strip-components=1

Temporarily set up the environment:

root #export PYTHONPATH="/tmp/portage/lib${PYTHONPATH:+:}${PYTHONPATH}"

root #export PATH="/tmp/portage/bin:${PATH}"

Run emerge:

It may be possible to run simply emerge, but it is recommended to prefix with the full path to be sure.

root #bin/emerge --info

Proceed to upgrade Portage itself, but if that fails (this is fairly likely - don't worry about it), attempt a full world upgrade.

Possible failures with older Bash

If >= Bash 5.0 isn't installed, EAPI 8 won't be usable, giving errors like:

 * Messages for package dev-qt/qtcore-5.15.2-r10:

 * ERROR: dev-qt/qtcore-5.15.2-r10::gentoo failed (pretend phase):
 *   >=bash-5.0 is required
 * 
 * Call stack:
 *   ebuild.sh, line 54:  Called __check_bash_version
 *   ebuild.sh, line 35:  Called die
 * The specific snippet of code:
 *              die ">=bash-${maj}.${min} is required"

In this case, try: FEATURES="preserve-libs" emerge -v1O sys-libs/readline app-shells/bash --ignore-built-slot-operator-deps=y.

Very old versions of Portage or Python (pre 2.7)

In very unusual (Gentoo archeology!) cases, the Ancient page may be useful.