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.

Warning
Do not extract to e.g. /root because when Portage drops privileges for e.g. fetching, it won't be able to import the modules and files from the rescue Portage copy. Suggestion is to use /tmp/portage/.

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.52.

Extract the tarball:

root #

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

root #

wget https://gitweb.gentoo.org/proj/portage.git/snapshot/portage-3.0.52.tar.gz

root #

tar xvf portage-3.0.52.tar.gz -C /tmp/portage --strip-components=1

Set up the environment

Temporarily set up the environment:

root #

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

root #

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

Test emerge

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

root #

bin/emerge --info

Upgrading the system safely

Tip
Please run the upgrade within screen or tmux if possible.

Tip
Check for sufficient free disk space before proceeding!

Tip
Ensure FEATURES=collision-protect is not set as it's obsolete. The default nowadays is FEATURES=protect-owned which should be sufficient.

Tip
Be sure to select the latest gcc already installed using gcc-config and binutils using binutils-config.

Proceed to upgrade Portage itself (if this fails, which is fairly likely, don't worry about it):

root #bin/emerge --verbose --update --oneshot sys-apps/portage

Check the version of Bash. This is necessary for newer EAPIs. If it is older than 5.0, forcefully upgrade it:

root #

# Check the output of bash --version! If it is 5.0 or newer, skip the next two lines!

root #

bash --version

root #

quickpkg app-shells/bash sys-libs/readline

root #

# Upgrade readline then bash (in this order)

root #

FEATURES="preserve-libs" bin/emerge -v1O sys-libs/readline app-shells/bash --ignore-built-slot-operator-deps=y

Attempt a full world upgrade:

root #

bin/emerge -a -uvDU @world --keep-going

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.