Python : diagnostiquer ModuleNotFoundError avec le bon interpréteur et venv

ParKelvin Carretero-Corrales

Vous avez installé une bibliothèque, mais votre programme affiche encore ModuleNotFoundError. Avant de réinstaller quoi que ce soit, vérifiez quel Python exécute le programme et quel Python utilise pip. Deux installations différentes peuvent expliquer ce décalage.

Ce guide vise un projet Python 3 utilisant pip. Les commandes principales sont prévues pour Linux et macOS ; un repère Windows figure plus bas. Si le projet impose un autre gestionnaire d’environnement, suivez sa procédure plutôt que de mélanger les outils.

1. Lire le nom réellement manquant dans le traceback

Le traceback est la suite d’appels affichée avec l’erreur. Relevez sa dernière ligne, puis le fichier et la ligne où l’import échoue. Le module absent peut être une dépendance appelée par une bibliothèque, pas celui que vous essayiez d’importer directement.

Demandez-vous aussi s’il s’agit d’une bibliothèque externe ou d’un module appartenant au projet. Un fichier local introuvable ne se répare pas nécessairement en installant un paquet sur Internet. Conservez les extraits utiles sans publier de chemins sensibles ni de secrets.

2. Identifier l’interpréteur réellement utilisé

Dans les exemples suivants, python3 doit désigner le Python que vous utilisez pour lancer le programme. Si votre commande de lancement emploie un chemin précis, reprenez ce même exécutable pour les contrôles.

python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python3 -m pip --version

sys.executable indique le chemin de l’interpréteur. Les deux lignes suivantes affichent son préfixe et celui de l’installation de base. Avec un environnement créé par venv, des valeurs différentes de sys.prefix et sys.base_prefix permettent d’identifier son utilisation.

La sortie de pip indique notamment son emplacement et la version de Python associée. La forme python3 -m pip appelle pip avec l’interpréteur choisi ; une commande pip isolée peut désigner autre chose dans votre terminal.

Si No module named pip apparaît, arrêtez l’installation à ce stade. Vérifiez l’environnement et la méthode d’installation de Python prévue par votre système ou votre projet : changer de commande au hasard ne résout pas l’ambiguïté.

3. Ne pas confondre le nom d’import et le nom du paquet

Le nom écrit dans import n’est pas obligatoirement celui à fournir à pip. Exemple documenté par la PyPA : la distribution Pillow fournit le paquet d’import PIL.

Ne transformez donc pas automatiquement « No module named X » en une installation de « X ». Vérifiez le nom dans la documentation officielle du projet et dans ses dépendances déclarées. La PyPA avertit qu’une installation fondée uniquement sur le nom d’import peut récupérer un paquet inattendu, voire malveillant.

4. Choisir l’environnement du projet avant d’installer

Si un environnement existe déjà, commencez par l’identifier : ne le recréez pas par-dessus pour tenter une réparation. S’il faut en créer un, placez-vous dans le répertoire du projet, choisissez la version Python attendue par celui-ci et vérifiez que le chemin .venv n’existe pas.

python3 -m venv .venv

Cette commande crée des fichiers locaux. Un environnement virtuel sépare les installations de paquets entre projets ; il ne doit pas servir à stocker votre code source. Sa création ne rend pas un paquet inconnu digne de confiance.

Vous pouvez appeler directement son Python, sans activer l’environnement dans le terminal :

.venv/bin/python -c "import sys; print(sys.executable)"
.venv/bin/python -m pip --version

Les commandes suivantes supposent que l’environnement retenu s’appelle .venv ; adaptez le chemin s’il porte un autre nom. Gardez ce même interpréteur pour les opérations qui le concernent. Cela évite de dépendre d’un terminal resté activé, ou non, sur un autre projet.

5. Inspecter, puis installer seulement les dépendances prévues

Remplacez NOM_DISTRIBUTION par le nom vérifié à l’étape précédente ; c’est un repère à adapter, pas un nom de paquet à installer.

.venv/bin/python -m pip show NOM_DISTRIBUTION

Examinez Name, Version et Location. Si pip ne trouve pas la distribution, cela décrit cet environnement précis : ce n’est pas la preuve qu’elle n’existe nulle part sur la machine.

Si la documentation du projet demande explicitement une installation depuis son fichier requirements.txt, et après avoir vérifié sa provenance et son contenu :

.venv/bin/python -m pip install -r requirements.txt

Cette étape télécharge et installe du logiciel. Certaines installations construisent des paquets en exécutant du code de compilation : ne la lancez pas sur un dépôt ou des dépendances non fiables. Ne modifiez pas le Python du système avec des privilèges administrateur pour contourner le problème.

6. Vérifier ce qui a changé, sans surinterpréter pip check

.venv/bin/python -m pip check

pip check contrôle la compatibilité des dépendances déclarées des paquets installés. Un résultat sans erreur ne prouve ni que tous les imports fonctionnent, ni que l’application est correcte ou exempte de vulnérabilités.

Relancez ensuite le programme ou les tests documentés avec le même interpréteur. Avant d’exécuter du code nouvellement récupéré, vérifiez là aussi sa provenance et les effets possibles de la commande.

Si l’erreur persiste : examiner le contexte de lancement

Python recherche les modules dans les emplacements de sys.path. Le répertoire du script peut notamment contenir un fichier portant le même nom qu’une bibliothèque et la masquer. Contrôlez donc l’arborescence du projet et la commande de lancement avant d’ajouter des chemins artificiellement.

Dans un éditeur ou un notebook, le Python exécutant le code peut différer de celui du terminal. Relevez sys.executable dans le contexte qui échoue et comparez-le au chemin contrôlé plus haut. Une installation réussie ailleurs n’est pas une validation de ce contexte.

Repère pour Windows PowerShell

Avec un environnement déjà créé par venv sous Windows, l’exécutable se trouve dans Scripts plutôt que bin. Depuis le dossier du projet, les mêmes contrôles deviennent :

.\.venv\Scripts\python.exe -c "import sys; print(sys.executable)"
.\.venv\Scripts\python.exe -m pip --version
.\.venv\Scripts\python.exe -m pip check

L’appel direct évite d’avoir à changer la politique d’exécution PowerShell simplement pour activer l’environnement.

À retenir

  • Identifier le module manquant dans l’erreur complète.
  • Vérifier l’interpréteur dans le contexte qui échoue.
  • Utiliser pip avec ce même Python.
  • Installer uniquement une distribution identifiée et prévue par le projet.
  • Rejouer le cas initial : une installation réussie n’est pas, à elle seule, une réparation.

Sources

Publications similaires