Python: réparer un pip cassé sous Ubuntu/Debian

Suite à une mauvaise manipulation, j’ai malencontreusement écrasé la version de pip installée par APT en lançant une commande du type :

pip install pip

ou, selon les cas :

sudo pip install --upgrade pip

Résultat : toute commande lancée avec pip se met à retourner cette erreur :

Traceback (most recent call last):
  File "/usr/bin/pip", line 9, in <module>
    from pip import main
ImportError: cannot import name mainLangage du code : JavaScript (javascript)

Pas glop.

Cette erreur arrive lorsque le script système /usr/bin/pip attend une ancienne interface interne de pip, alors qu’une version plus récente de pip a été installée par-dessus via pip lui-même. En clair, APT et pip se marchent dessus. Et, comme souvent dans ce genre de duel, c’est votre terminal qui prend les coups.

Voici comment réparer proprement pip sous Ubuntu ou Debian, puis éviter de recasser l’installation système.

Kinsta: Premium Managed WordPress hosting

Pourquoi l’erreur “cannot import name main” apparaît ?

L’erreur vient souvent d’un mélange entre deux mondes :

apt, qui gère les paquets Python fournis par la distribution ;
pip, qui installe des paquets depuis l’écosystème Python ;
un script /usr/bin/pip généré pour une ancienne version ;
une version de pip installée manuellement dans un emplacement prioritaire.

Historiquement, certains scripts pip importaient main avec une ligne du type :

from pip import mainLangage du code : JavaScript (javascript)

Or, les versions modernes de pip ont changé leur organisation interne. Résultat : le vieux lanceur appelle une fonction qui n’existe plus à cet endroit.

Ce problème a été largement documenté après les mises à jour vers pip 10 et suivantes. L’équipe pip recommande d’ailleurs d’appeler pip via python -m pip lorsque le script pip lui-même pose problème. Voir l’issue pip liée à cette erreur.

Première vérification : quelle commande pip est appelée ?

Avant de supprimer quoi que ce soit, vérifiez quel binaire est utilisé :

command -v pip
command -v pip3
which pip
which pip3

Vérifiez aussi la version, si la commande répond encore :

pip --version
pip3 --version
python3 -m pip --version

Si pip est cassé mais que cette commande fonctionne encore :

python3 -m pip --version

vous pouvez déjà utiliser python3 -m pip comme solution temporaire. C’est souvent plus fiable que d’appeler le wrapper pip directement.

Solution rapide : réinstaller pip avec APT

Sur Ubuntu ou Debian, si vous voulez retrouver une version de pip cohérente avec le système, le plus propre consiste à purger puis réinstaller le paquet APT.

Commencez par désinstaller la version pip installée dans l’environnement Python, si la commande fonctionne encore :

python3 -m pip uninstall pip

Ensuite, purgez le paquet APT :

sudo apt purge --autoremove python3-pip

Puis réinstallez pip depuis les dépôts de la distribution :

sudo apt update
sudo apt install python3-pip

Vérifiez ensuite :

pip3 --version
python3 -m pip --version

Sur un Ubuntu récent, vous pouvez obtenir un résultat de ce type :

pip 24.0 from /usr/lib/python3/dist-packages/pip (python 3.12)Langage du code : JavaScript (javascript)

Si pip3 fonctionne à nouveau, le paquet système est réparé.

Le plus lu : Résoudre l’erreur HTTP/2 stream was not closed cleanly

Ne réparez pas pip avec sudo pip install pip

La tentation est grande de résoudre un problème pip avec pip lui-même :

sudo pip install --upgrade pip

Sur Ubuntu ou Debian, c’est précisément ce qui casse souvent l’installation.

Les distributions Linux gèrent leur Python système avec leur gestionnaire de paquets. Depuis PEP 668, les environnements Python gérés par la distribution peuvent être marqués comme externally managed, afin d’indiquer aux outils comme pip qu’ils ne doivent pas installer ni supprimer des paquets dans l’environnement global par défaut. Voir PEP 668.

La spécification Python Packaging explique aussi que le marqueur EXTERNALLY-MANAGED permet à une installation Python d’indiquer aux outils comme pip qu’ils doivent orienter l’utilisateur vers les environnements virtuels plutôt que modifier l’installation système. Voir la spécification “Externally Managed Environments”.

En clair : laissez APT gérer le pip système. Utilisez des environnements virtuels pour vos projets. Tout le monde respire mieux.

Codeable: trouvez les meilleurs développeurs WordPress

Méthode recommandée : utiliser python3 -m pip

Même quand tout fonctionne, il est préférable d’appeler pip avec le module Python correspondant :

python3 -m pip install nom-du-paquet

Cette forme garantit que vous utilisez le pip associé à l’interpréteur python3 appelé. C’est particulièrement utile quand plusieurs versions de Python cohabitent sur la machine.

Le guide officiel Python Packaging utilise justement python -m pip dans son workflow d’installation en environnement virtuel. Voir le guide officiel pip + venv.

Installer des paquets Python sans casser le système

Sur une machine Ubuntu ou Debian moderne, il faut distinguer trois cas.

1. Paquet utilisé par le système

Si le paquet Python est fourni par Ubuntu ou Debian, installez-le avec APT :

sudo apt install python3-requests

C’est la méthode la plus propre pour les dépendances système.

2. Paquet utilisé par un projet

Pour un projet Python, utilisez un environnement virtuel :

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install requests

Dans un venv, vous pouvez mettre pip à jour sans toucher au Python système. C’est là que pip install --upgrade pip a sa place.

3. Outil Python en ligne de commande

Pour installer un outil Python global en tant qu’application, utilisez plutôt pipx :

sudo apt install pipx
pipx ensurepath
pipx install black

pipx installe chaque outil dans son propre environnement isolé. C’est beaucoup plus propre que de polluer le Python système avec des utilitaires globaux.

Cas Ubuntu récent : erreur “externally-managed-environment”

Sur Ubuntu récent, si vous lancez :

pip3 install requests

vous pouvez obtenir :

error: externally-managed-environmentLangage du code : HTTP (http)

Ce n’est pas la même erreur que ImportError: cannot import name main, mais elle vient de la même philosophie : éviter que pip modifie l’environnement Python géré par la distribution.

Le plus lu : Projet Honey Pot : 1 milliard de spams traités

Dans ce cas, utilisez l’une de ces solutions :

installer le paquet via APT si disponible ;
créer un environnement virtuel avec python3 -m venv ;
installer un outil CLI avec pipx ;
éviter --break-system-packages sauf cas très précis et assumé.

Le contournement --break-system-packages porte bien son nom. Ce n’est pas une décoration, c’est un avertissement avec des bottes de sécurité.

Faut-il encore utiliser Python 2.7 ?

L’ancien article mentionnait python2.7 et update-alternatives --config python. Aujourd’hui, ce n’est plus une bonne direction pour réparer pip sur une machine moderne.

Python 2 est obsolète depuis longtemps. Sur Ubuntu/Debian récents, concentrez-vous sur Python 3 :

python3 --version
pip3 --version
python3 -m pip --version

Évitez aussi de changer le binaire python global avec update-alternatives pour corriger un problème pip. Cela peut casser des scripts système qui s’attendent à un comportement précis.

La réparation moderne passe par python3-pip, python3 -m pip, les environnements virtuels et APT.

Nettoyer les restes d’un pip installé dans /usr/local

Si, après réinstallation, pip continue d’appeler une mauvaise version, vérifiez les chemins :

type -a pip
type -a pip3
type -a python3

Vous pouvez voir plusieurs entrées, par exemple :

/usr/local/bin/pip3
/usr/bin/pip3

Si /usr/local/bin/pip3 passe avant /usr/bin/pip3, votre shell peut appeler une version installée manuellement au lieu de celle gérée par APT.

Inspectez le fichier avant de le supprimer :

ls -l /usr/local/bin/pip*
head -n 20 /usr/local/bin/pip3

Si vous êtes certain qu’il s’agit d’un wrapper pip installé manuellement et devenu problématique, déplacez-le plutôt que de le supprimer directement :

sudo mkdir -p /root/pip-broken-backup
sudo mv /usr/local/bin/pip /usr/local/bin/pip3 /root/pip-broken-backup/ 2>/dev/null || trueLangage du code : JavaScript (javascript)

Puis relancez :

hash -r
pip3 --version
python3 -m pip --version

Le shell peut garder en cache l’emplacement d’une commande. hash -r lui demande d’oublier ses anciens chemins. Petit ménage mental pour Bash.

Réparer pip avec ensurepip ?

Python fournit un module ensurepip capable d’installer ou mettre à jour pip dans certains environnements Python.

La documentation officielle indique que ensurepip permet d’amorcer l’installateur pip dans une installation Python ou un environnement virtuel. Voir la documentation Python de ensurepip.

Sur Ubuntu/Debian, cependant, le Python système est géré par APT. Pour réparer le pip système, préférez donc :

sudo apt install --reinstall python3-pip

Gardez ensurepip pour les environnements virtuels, les installations Python compilées à la main, ou les cas où vous savez exactement quel interpréteur vous réparez.

Solution complète recommandée

Voici la séquence que je recommande sur Ubuntu ou Debian quand pip est cassé :

type -a pip pip3 python3 || true

python3 -m pip uninstall pip || true

sudo apt purge --autoremove python3-pip
sudo apt update
sudo apt install python3-pip

hash -r

pip3 --version
python3 -m pip --versionLangage du code : JavaScript (javascript)

Si une version cassée reste prioritaire dans /usr/local/bin, déplacez-la après vérification :

ls -l /usr/local/bin/pip*
sudo mkdir -p /root/pip-broken-backup
sudo mv /usr/local/bin/pip* /root/pip-broken-backup/
hash -r
pip3 --versionLangage du code : JavaScript (javascript)

Ne lancez cette dernière séquence que si vous avez bien confirmé que ces fichiers /usr/local/bin/pip* sont des restes problématiques d’une installation manuelle.

Le plus lu : Mettre à jour MySQL client, server et apt-config

Créer ensuite un environnement virtuel propre

Une fois pip réparé, n’installez pas vos dépendances de projet dans le Python système. Créez un environnement virtuel :

sudo apt install python3-venv

mkdir -p ~/projets/demo-python
cd ~/projets/demo-python

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install requestsLangage du code : JavaScript (javascript)

À partir de là, les paquets installés restent isolés dans .venv. Vous pouvez mettre pip à jour dans cet environnement sans toucher au système.

Le guide officiel Python Packaging recommande justement cette approche : créer un environnement virtuel, l’activer, puis installer les paquets avec pip à l’intérieur de cet environnement. Voir le guide officiel.

Résumé rapide

Si pip renvoie :

ImportError: cannot import name mainLangage du code : JavaScript (javascript)

réparez-le ainsi sur Ubuntu/Debian :

python3 -m pip uninstall pip || true
sudo apt purge --autoremove python3-pip
sudo apt update
sudo apt install python3-pip
pip3 --versionLangage du code : JavaScript (javascript)

Ensuite, pour vos projets :

python3 -m venv .venv
source .venv/bin/activate
python -m pip install nom-du-paquet

Et évitez désormais :

sudo pip install --upgrade pip

Le pip système appartient à APT. Les dépendances de projet appartiennent au venv. Chacun son jardin, moins de bazar.

Conclusion

L’erreur ImportError: cannot import name main apparaît souvent après avoir mis à jour pip manuellement par-dessus la version fournie par Ubuntu ou Debian.

La bonne correction consiste à restaurer le paquet python3-pip via APT, puis à utiliser python3 -m pip et des environnements virtuels pour les projets.

Sur les distributions modernes, PEP 668 renforce justement cette séparation entre Python système et paquets installés par pip. C’est une bonne chose : on évite de casser des outils système pour installer une dépendance de projet.

En résumé : ne mettez pas à jour le pip système avec pip. Laissez APT gérer le système, et laissez vos venvs faire le sale boulot applicatif. Tout le monde sera plus heureux, terminal compris.