Tu viens d’installer un paquet avec pip, tu lances ton script… et Python répond « ModuleNotFoundError: No module named … ». Rageant ! Dans 99 % des cas, la cause fait partie de cette liste de cinq. Ce guide t’apprend à diagnostiquer l’erreur ModuleNotFoundError Python en deux commandes, puis à la corriger pour de bon, sous Windows, macOS et Linux, dans le terminal comme dans VS Code.
Voici l’erreur dans sa forme la plus classique :
Traceback (most recent call last):
File "C:\projets\meteo\app.py", line 1, in <module>
import requests
ModuleNotFoundError: No module named 'requests'Le message est clair : au moment d’exécuter import requests, Python n’a trouvé aucun module de ce nom. Mais pourquoi, alors que tu viens de taper pip install requests et que pip a répondu Successfully installed ? C’est tout le paradoxe de l’erreur ModuleNotFoundError Python : le paquet est souvent bien installé… mais pas là où ton Python le cherche.
- Le paquet n’est pas installé du tout.
- Il est installé pour un autre Python que celui qui exécute ton script.
- L’environnement virtuel n’est pas activé (ou VS Code utilise le mauvais interpréteur).
- Le nom à installer n’est pas le même que le nom à importer.
- Un problème d’import entre tes propres fichiers.
Comment Python trouve un module
Quand tu écris import requests, Python parcourt une liste de dossiers, dans l’ordre, à la recherche de requests : c’est le chemin de recherche, stocké dans sys.path. Il contient notamment :
- le dossier du script que tu exécutes ;
- les dossiers de la bibliothèque standard de Python ;
- le dossier
site-packages, où pip installe les paquets.
Le point essentiel : chaque installation de Python a son propre site-packages. Si tu as Python 3.12 et Python 3.13 sur ton poste, plus un environnement virtuel, tu as trois dossiers site-packages différents. Un paquet installé dans l’un est invisible pour les autres.
Le diagnostic en deux commandes
Avant de corriger quoi que ce soit, ajoute temporairement ces deux lignes en haut de ton script (avant l’import qui échoue) :
import sys
print("Python utilisé :", sys.executable)Puis, dans le terminal, demande à pip pour quel Python il travaille :
pip --version
# pip 25.x from C:\Users\lea\AppData\Local\Programs\Python\Python313\Lib\site-packages\pip (python 3.13)Compare les deux chemins :
| Résultat | Diagnostic | Cause |
|---|---|---|
| Les deux chemins pointent vers le même Python | pip et ton script utilisent le même interpréteur | Cause n°1, n°4 ou n°5 |
| Les chemins sont différents | Tu installes dans un Python et tu exécutes avec un autre | Cause n°2 ou n°3 |
Ce simple test résout la majorité des cas. Voyons maintenant chaque cause en détail.
Cause n°1 : le paquet n’est pas installé
C’est la cause la plus simple : tu as copié un code trouvé en ligne, ou cloné un projet, sans installer ses dépendances. Vérifie avec :
python -m pip show requestsSi la commande répond WARNING: Package(s) not found, installe-le :
python -m pip install requestsSi le projet contient un fichier requirements.txt, installe toutes les dépendances d’un coup :
python -m pip install -r requirements.txtpython -m pip exécute pip avec le Python que tu appelles. Tu es certain que le paquet est installé exactement là où ce Python le cherchera. C’est la recommandation officielle de la documentation Python, et cela élimine à lui seul la cause n°2.
Cause n°2 : le paquet est installé pour un autre Python
C’est la cause la plus fréquente, surtout sous Windows et macOS, où plusieurs versions de Python cohabitent souvent (installée depuis python.org, depuis le Microsoft Store, via Homebrew, avec Anaconda…). La commande pip peut appartenir à l’une, et python à une autre.
Sous Windows, le lanceur py permet de choisir précisément la version :
py --list # liste les versions de Python installées
py -3.13 -m pip install requests
py -3.13 app.pySous macOS et Linux, utilise explicitement python3 :
python3 -m pip install requests
python3 app.pyWindows contient des « alias d’exécution » : taper python dans un terminal peut ouvrir le Microsoft Store ou lancer une autre version que celle installée depuis python.org. Si sys.executable affiche un chemin contenant WindowsApps, désactive ces alias dans Paramètres → Applications → Paramètres d’applications avancés → Alias d’exécution d’application (décoche python.exe et python3.exe).
Sur les distributions récentes (Debian 12, Ubuntu 23.04 et plus, Homebrew), pip install dans le Python du système affiche l’erreur externally-managed-environment. Ce n’est pas un bug : le système te demande de ne pas modifier son Python. La solution propre est un environnement virtuel (cause n°3). Évite l’option --break-system-packages, qui porte bien son nom.
Cause n°3 : l’environnement virtuel n’est pas activé
Un environnement virtuel (venv) est un dossier qui contient un Python isolé, avec son propre site-packages. C’est la bonne pratique pour chaque projet : les dépendances d’un projet ne perturbent pas celles d’un autre. Si tu ne connais pas encore les environnements virtuels, notre guide sur l’environnement virtuel Python explique tout en détail.
Le scénario classique : tu installes le paquet dans le venv, puis tu lances le script dans un nouveau terminal où le venv n’est pas activé. Ou l’inverse.
# Créer l'environnement (une fois par projet)
python -m venv .venv
# L'activer (à chaque nouveau terminal)
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# macOS / Linux
source .venv/bin/activate
# Installer et exécuter DANS le venv
python -m pip install requests
python app.pyUne fois activé, le nom de l’environnement apparaît au début de l’invite de commande : (.venv) PS C:\projets\meteo>. Si tu ne le vois pas, le venv n’est pas actif.
Si tu obtiens « l’exécution de scripts est désactivée sur ce système », autorise les scripts locaux pour ton utilisateur, une seule fois : Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
Dans VS Code : choisir le bon interpréteur
VS Code peut exécuter ton script avec un autre Python que celui de ton terminal. Résultat : tout fonctionne dans le terminal, et l’erreur apparaît quand tu cliques sur le bouton ▶️ (ou l’inverse).
- Ouvre la palette de commandes avec
Ctrl+Shift+P(Cmd+Shift+Psur Mac). - Tape Python: Select Interpreter.
- Choisis celui de ton projet, marqué
.venv(.\.venv\Scripts\python.exesous Windows).
L’interpréteur choisi s’affiche en bas à droite de la fenêtre. Les nouveaux terminaux ouverts dans VS Code activeront alors automatiquement le venv. Si l’import reste souligné en jaune alors que le script fonctionne, c’est le même problème : l’analyseur de code (Pylance) utilise un autre interpréteur.
Dans un notebook, installe les paquets avec la commande magique %pip install requests (et non !pip install) : elle installe dans le noyau (kernel) réellement utilisé par le notebook.
Cause n°4 : le nom à installer n’est pas le nom à importer
Le nom d’un paquet sur PyPI (celui que tu donnes à pip) n’est pas toujours le nom du module que tu importes. C’est un piège très courant :
| Tu importes… | Tu dois installer… |
|---|---|
import cv2 | opencv-python |
from PIL import Image | Pillow |
import sklearn | scikit-learn |
from bs4 import BeautifulSoup | beautifulsoup4 |
import yaml | PyYAML |
from dotenv import load_dotenv | python-dotenv |
import serial | pyserial |
import win32api | pywin32 |
import docx | python-docx |
import jwt | PyJWT |
import MySQLdb | mysqlclient |
import mysql.connector | mysql-connector-python |
pip install cv2, pip install sklearn ou un nom mal orthographié peuvent installer un paquet inutile, obsolète, voire malveillant : des attaquants publient volontairement des paquets aux noms proches de paquets populaires (typosquatting). Vérifie toujours le nom exact sur pypi.org ou dans la documentation officielle de la librairie.
Note aussi que Python est sensible à la casse : import Requests ou import Flask échoueront, il faut écrire import requests et from flask import Flask.
Cause n°5 : les imports entre tes propres fichiers
Cette dernière cause concerne ton code. Elle apparaît quand ton projet grandit et que tu le découpes en plusieurs fichiers et dossiers.
Un de tes fichiers porte le nom d’un module
Si ton dossier contient un fichier requests.py, random.py, email.py ou csv.py, il masque le vrai module : Python trouve ton fichier en premier (le dossier du script est en tête de sys.path). Selon les cas, tu obtiens ModuleNotFoundError sur un sous-module ou une ImportError étrange.
mon-projet/
├── app.py # import requests
└── requests.py # ❌ ton fichier de test masque la vraie librairieRenomme ton fichier (test_requetes.py) et supprime le dossier __pycache__ qui a pu être créé à côté.
Le script est lancé depuis le mauvais dossier
Prenons ce projet :
meteo/
├── app/
│ ├── __init__.py
│ ├── main.py # from app.services import previsions
│ └── services.py
└── tests/Si tu lances python app/main.py, Python ajoute le dossier app/ à sys.path, pas le dossier meteo/. Le package app est donc introuvable :
ModuleNotFoundError: No module named 'app'La solution : lance-le comme un module, depuis la racine du projet :
cd meteo
python -m app.mainAvec -m, Python ajoute le dossier courant (meteo/) au chemin de recherche, et le package app est trouvé.
- Place un fichier
__init__.py(même vide) dans chaque dossier qui sert de package. - Utilise des imports absolus depuis la racine du projet :
from app.services import previsions. - Lance tes scripts depuis la racine du projet, avec
python -m. - Évite de modifier
sys.pathà la main dans le code : ça marche sur ton poste et casse ailleurs.
Cas particuliers : Docker, serveur et tâches planifiées
L’erreur peut aussi apparaître alors que tout fonctionne sur ton poste. Trois situations reviennent souvent.
Dans un conteneur Docker. Le conteneur a son propre Python, totalement indépendant de celui de ton ordinateur. Les paquets doivent être installés dans l’image, généralement avec une ligne RUN pip install --no-cache-dir -r requirements.txt dans le Dockerfile. Si tu ajoutes une dépendance, pense à reconstruire l’image (docker compose up -d --build).
Sur un serveur ou chez un hébergeur. Le requirements.txt n’est pas toujours installé automatiquement lors du déploiement. Vérifie que la commande d’installation fait partie de ta procédure de mise en ligne, et que le serveur web (Gunicorn, uWSGI, Passenger) utilise bien le Python de l’environnement virtuel du projet.
Dans une tâche planifiée (cron, Planificateur de tâches Windows). Ces outils démarrent avec un environnement minimal : le venv n’est pas activé et le PATH est réduit. Utilise toujours le chemin complet de l’interpréteur du venv :
# crontab : exécuter le script chaque nuit à 2 h avec le Python du venv
0 2 * * * /home/lea/projets/meteo/.venv/bin/python /home/lea/projets/meteo/import.pyModuleNotFoundError Python : l’arbre de décision
Quand l’erreur apparaît, suis ces questions dans l’ordre :
- Le module est-il à toi ou à une librairie ? À toi → cause n°5. Librairie → continue.
sys.executableetpip --versionpointent-ils vers le même Python ? Non → cause n°2 ou n°3 : utilisepython -m pip installavec le bon Python, ou active le venv.python -m pip show nom-du-paquettrouve-t-il le paquet ? Non → cause n°1 (ou n°4 : vérifie le nom à installer).- Ça marche dans le terminal mais pas dans l’éditeur ? → sélectionne le bon interpréteur dans VS Code (cause n°3).
Éviter l’erreur dans tes futurs projets
Quelques habitudes suffisent pour ne presque plus jamais rencontrer l’erreur :
# 1. Un environnement virtuel par projet
python -m venv .venv
# 2. Toujours installer avec python -m pip, venv activé
python -m pip install requests flask
# 3. Enregistrer les dépendances du projet
python -m pip freeze > requirements.txt
# 4. Sur un autre poste (ou après un git clone)
python -m pip install -r requirements.txtAjoute .venv/ à ton .gitignore : on ne versionne pas l’environnement, seulement le requirements.txt qui permet de le recréer. Des outils modernes comme uv ou Poetry automatisent tout ce processus (création de l’environnement, verrouillage des versions) et deviennent de plus en plus populaires.
Dépannage express
| Message ou situation | Cause probable | Correction |
|---|---|---|
No module named 'requests' juste après pip install | pip et python différents | python -m pip install requests |
No module named 'cv2' | Mauvais nom de paquet | python -m pip install opencv-python |
| Fonctionne dans le terminal, pas dans VS Code | Mauvais interpréteur | Python: Select Interpreter |
No module named 'app' | Script lancé depuis le mauvais dossier | python -m app.main depuis la racine |
No module named 'tkinter' (Linux) | Module système non installé | sudo apt install python3-tk |
No module named '_ctypes' ou '_ssl' | Python compilé sans dépendances système | Réinstaller Python depuis une source officielle |
externally-managed-environment | Python du système protégé | Créer un environnement virtuel |
| Erreur seulement sur le serveur | Dépendances non installées en production | pip install -r requirements.txt sur le serveur |
FAQ
Quelle différence entre ModuleNotFoundError et ImportError ?
ModuleNotFoundError est un cas particulier d’ImportError (elle en hérite depuis Python 3.6) : le module lui-même est introuvable. ImportError seule signifie souvent que le module existe, mais que l’élément importé n’y est pas, par exemple from flask import Flaskk.
Faut-il installer les paquets avec sudo sous Linux ?
Non. sudo pip install modifie le Python du système et peut casser des outils de ta distribution. Utilise un environnement virtuel, ou pipx pour les outils en ligne de commande (pipx install black).
Pourquoi l’erreur ModuleNotFoundError Python apparaît-elle après une mise à jour de Python ?
Chaque version de Python a son propre site-packages. En passant de 3.12 à 3.13, tes paquets ne sont pas transférés : recrée ton environnement virtuel avec la nouvelle version et réinstalle les dépendances depuis requirements.txt.
Mon module est bien installé, mais la version est trop ancienne ?
Ce n’est alors plus une ModuleNotFoundError mais souvent une ImportError ou une AttributeError. Mets à jour le paquet avec python -m pip install --upgrade nom-du-paquet.
Conclusion
L’erreur ModuleNotFoundError Python se résume presque toujours à une question : est-ce que le Python qui exécute mon script est celui dans lequel j’ai installé le paquet ? Les deux commandes de diagnostic (sys.executable et pip --version) te donnent la réponse en dix secondes. Ensuite, la correction est simple : python -m pip install, activation du venv, bon interpréteur dans VS Code, bon nom de paquet, ou lancement avec python -m pour tes propres modules.
Prends l’habitude d’un environnement virtuel par projet et de python -m pip, et cette erreur deviendra très rare. Pour t’entraîner sur un vrai projet Python, essaie notre tutoriel d’application de diagnostic PC avec Flask. Et la documentation officielle sur l’installation de modules Python reste la référence.
