ModuleNotFoundError Python : Toutes les Causes et Solutions

ModuleNotFoundError: No module named 'xxx' — Python ne trouve pas le module que tu essaies d'importer. C'est une des erreurs les plus frustrantes pour les débutants parce que les causes sont variées. Voici les 6 plus fréquentes.

1. Le module n'est pas installé

La cause la plus simple : tu n'as pas installé le package avec pip.

# ❌ Tu fais ça dans ton code
import requests  # ModuleNotFoundError: No module named 'requests'

# ✅ Installe le module d'abord
pip install requests

# Si tu as Python 3 et Python 2 sur la même machine
pip3 install requests

Vérifier si un module est installé :

# Lister tous les modules installés
pip list

# Chercher un module spécifique
pip show requests

2. Mauvais environnement Python (le piège n°1)

Tu as installé le module dans un Python, mais tu exécutes le script avec un autre. C'est le problème le plus courant et le plus frustrant.

# ❌ Installé avec pip (Python global)
pip install requests

# ❌ Mais tu exécutes dans un venv qui n'a pas requests
python script.py  # ModuleNotFoundError!

# ✅ Vérifier quel Python tu utilises
which python     # /usr/bin/python ? ~/.venv/bin/python ?
which pip        # Le pip correspond-il au même Python ?

# ✅ Utiliser python -m pip pour être sûr
python -m pip install requests
# Garantit que pip installe pour LE Python qui exécute la commande

Avec un environnement virtuel :

# Créer et activer un venv
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# Maintenant pip installe dans le venv
pip install requests
python script.py  # ✅ Utilise le même environnement

3. Nom du module différent du nom du package pip

Le nom que tu import n'est pas toujours le même que celui que tu pip install.

# ❌
pip install PIL  # N'existe pas !

# ✅
pip install Pillow
# Puis dans ton code : from PIL import Image

4. Ton fichier a le même nom qu'un module

Tu as nommé ton fichier random.py, json.py, ou math.py — Python importe ton fichier au lieu du module standard.

# ❌ Ton fichier s'appelle random.py
import random
print(random.randint(1, 10))
# ImportError ou AttributeError — Python importe ton random.py !

# ✅ Renomme ton fichier
# random.py → mon_random.py ou generateur.py

Les noms à éviter absolument : random.py, json.py, math.py, os.py, sys.py, test.py, email.py, string.py, collections.py.

Comment détecter :

import random
print(random.__file__)  # Si ça pointe vers TON dossier → c'est le problème

5. Mauvais chemin d'import (import relatif)

projet/
├── main.py
├── utils/
│   ├── __init__.py
│   └── helpers.py
└── config.py

# ❌ Depuis main.py
from helpers import ma_fonction  # ModuleNotFoundError

# ✅ Import avec le chemin complet
from utils.helpers import ma_fonction

# ❌ Depuis helpers.py, importer config.py
import config  # Peut échouer selon comment tu lances le script

# ✅ Import relatif (dans un package)
from .. import config  # Remonte d'un niveau

Règle : lance toujours ton script depuis la racine du projet, pas depuis un sous-dossier.

# ❌ Depuis le sous-dossier
cd utils && python helpers.py

# ✅ Depuis la racine
python -m utils.helpers
# Ou
python main.py

6. Module local sans __init__.py

Pour que Python reconnaisse un dossier comme un package importable, il faut un fichier __init__.py (même vide).

# ❌ Pas de __init__.py
projet/
├── main.py
└── utils/
    └── helpers.py  # from utils.helpers import ... → ModuleNotFoundError

# ✅ Ajouter __init__.py
projet/
├── main.py
└── utils/
    ├── __init__.py   # Fichier vide, mais nécessaire
    └── helpers.py    # Maintenant l'import fonctionne

# Créer le fichier rapidement
touch utils/__init__.py

Résumé

FAQ

J'ai installé le module mais Python ne le trouve toujours pas ?
Tu as probablement plusieurs versions de Python. Utilise python -m pip install module pour être sûr d'installer dans le bon Python. Vérifie avec which python et which pip qu'ils pointent vers le même endroit.

C'est quoi la différence entre pip et pip3 ?
pip peut pointer vers Python 2 ou 3 selon ta machine. pip3 pointe toujours vers Python 3. Pour être sûr : utilise python3 -m pip install.

Comment voir où Python cherche les modules ?
import sys; print(sys.path) affiche tous les dossiers où Python cherche les modules. Si ton dossier n'est pas dans la liste, Python ne trouvera pas ton module.

Pour les bases de Python : le guide complet débutant, les fonctions et l'IndentationError expliquée.

Envie de pratiquer ? GoGoKodo propose des ateliers interactifs pour apprendre Python en codant directement dans le navigateur — 100% gratuit.