Si Python importe un fichier de votre projet au lieu du paquet que vous avez installé, identifiez d'abord le fichier que Python charge. Sur macOS, vérifiez l'interpréteur actif, le chemin du module importé et tout fichier ou dossier du projet portant le même nom. Renommez le fichier local en conflit, supprimez son cache de bytecode obsolète si nécessaire et exécutez le projet avec l'environnement Python prévu.

1. Vérifier quel Python et quel module sont utilisés

Dans Terminal, accédez au dossier du projet et demandez à Python d'indiquer l'origine du module. Remplacez requests par le nom d'importation qui échoue ; par exemple, un paquet installé sous le nom Pillow est importé sous le nom PIL.

cd "/path/to/your/project"
command -v python3
python3 -c 'import sys, importlib.util; name = "requests"; print("Python:", sys.executable); print("Module:", importlib.util.find_spec(name))'

Un résultat avec une origin située sous le répertoire de votre projet, comme .../requests.py, indique un fichier local qui masque le paquet. Python place le répertoire du script ou le répertoire de travail actuel au début de son chemin de recherche, de sorte qu'un module local de même nom peut avoir la priorité sur un paquet installé. Documentation sur le chemin de recherche des modules de Python

Si la commande renvoie None, cet interpréteur ne parvient pas à trouver le module sous ce nom. Si elle indique un emplacement dans site-packages, le conflit se trouve peut-être ailleurs : votre application lance peut-être un interpréteur différent, le nom d'importation diffère peut-être du nom d'installation du paquet, ou l'erreur peut survenir au sein d'une dépendance du paquet.

2. Trouver et renommer le conflit local

Recherchez dans le projet un fichier nommé d'après l'importation, comme requests.py, ou un répertoire portant ce nom. Vérifiez également la présence de noms courants de la bibliothèque standard tels que email.py, json.py ou typing.py. Renommez le fichier ou le répertoire avec un nom spécifique au projet, puis mettez à jour toutes les importations qui faisaient référence à ce module local. Évitez de le renommer simplement avec un autre nom courant de paquet ou de la bibliothèque standard.

Si le fichier en conflit est un module voulu du projet, conservez-le mais donnez-lui un nom distinctif et importez-le via la structure de paquets de votre projet. Un fichier de projet qui partage par hasard le nom d'un paquet tiers est particulièrement susceptible de provoquer des importations partielles déroutantes ou des erreurs d'attributs manquants.

Après avoir renommé, supprimez uniquement le répertoire __pycache__ correspondant s'il en reste un à côté de l'ancien fichier. Python vérifie normalement les dates de modification des fichiers sources et actualise automatiquement les caches de bytecode ; la suppression du cache correspondant est une étape de nettoyage, pas un substitut à la résolution du conflit de noms. Documentation de Python sur les modules et le bytecode

3. S'assurer que le paquet appartient au Python exécuté

Sur macOS, il est fréquent d'avoir plusieurs installations de Python ou plusieurs environnements de projet. L'exécutable affiché sous sys.executable est l'interpréteur derrière la commande que vous venez d'exécuter. Installez les paquets via cet interpréteur afin que pip et Python ne pointent pas par accident vers des environnements différents :

python3 -m pip show requests
python3 -m pip install requests

Utilisez le nom de distribution du paquet avec pip show et son nom d'importation avec Python. Ils peuvent différer ; par exemple, Pillow est couramment importé sous le nom PIL. Un résultat « package not found » provenant de pip show signifie que cette distribution n'est pas installée pour l'interpréteur utilisé par cette commande.

Pour un environnement spécifique au projet, créez et activez un environnement virtuel depuis le répertoire du projet, puis installez-y la dépendance :

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -c 'import requests; print(requests.__file__)'

Lorsque l'environnement est actif, python doit pointer vers son propre interpréteur. La dernière commande affiche le chemin réel du fichier chargé ; vérifiez qu'il se trouve bien sous .venv plutôt qu'à la racine de votre projet. Les environnements virtuels isolent les paquets du projet des autres environnements et se créent avec python -m venv. Documentation de venv dans Python

4. Vérifier les surcharges de chemins et réexécuter proprement

Si le module pointe toujours vers un emplacement inattendu, inspectez le chemin de recherche de Python et toute surcharge par PYTHONPATH :

python -c 'import os, sys; print("PYTHONPATH:", os.environ.get("PYTHONPATH")); print("sys.path:"); print("\n".join(sys.path))'

sys.path est initialisé à l'aide de PYTHONPATH et des valeurs par défaut dépendantes de l'installation ; lors des invocations courantes, Python ajoute également en tête le répertoire du script ou le répertoire de travail actuel. Supprimez une variable PYTHONPATH indésirable du shell actif avec unset PYTHONPATH, puis relancez le diagnostic. Pour les paramètres persistants, inspectez le fichier de configuration du shell dans lequel elle a été définie et supprimez ou corrigez cette ligne d'exportation. Documentation de sys.path dans Python

Redémarrez le processus Python après avoir renommé des fichiers ou changé d'environnement : un interpréteur déjà en cours d'exécution peut conserver en mémoire les modules qu'il a importés. Répétez ensuite la vérification de l'origine et lancez la commande ou l'application comme vous le faites habituellement. Si l'origine est correcte mais que l'importation échoue toujours, lisez l'intégralité de la trace d'appels (traceback) ; elle peut indiquer une dépendance manquante ou une erreur survenue lors du chargement du paquet, plutôt qu'un conflit de nom.

Sources