Si Python importa un archivo de tu proyecto en lugar del paquete que instalaste, primero identifica qué archivo está cargando Python. En macOS, verifica el intérprete activo, la ruta del módulo importado y cualquier archivo o carpeta del proyecto que tenga el mismo nombre. Cambia el nombre del archivo local en conflicto, elimina su caché de bytecode obsoleta si es necesario y ejecuta el proyecto con el entorno de Python previsto.

1. Comprobar qué Python y módulo se están utilizando

En la Terminal, ve a la carpeta del proyecto y pide a Python que indique el origen del módulo. Reemplaza requests por el nombre de importación que esté fallando; por ejemplo, un paquete instalado como Pillow se importa como 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 resultado con un origin dentro del directorio de tu proyecto, como .../requests.py, apunta a un archivo local que está eclipsando al paquete. Python sitúa el directorio del script o el directorio de trabajo actual al principio de su ruta de búsqueda, por lo que un módulo local con el mismo nombre puede tener prioridad sobre un paquete instalado. Documentación sobre la ruta de búsqueda de módulos de Python

Si el comando devuelve None, ese intérprete no puede encontrar el módulo con ese nombre. Si muestra una ubicación en site-packages, la colisión puede estar en otra parte: tu aplicación podría iniciar un intérprete diferente, el nombre de importación podría diferir del nombre de instalación del paquete o el error podría originarse dentro de una dependencia del paquete.

2. Encontrar y cambiar el nombre del conflicto local

Busca en el proyecto un archivo que lleve el nombre de la importación, como requests.py, o un directorio con ese nombre. Comprueba también si existen nombres comunes de la biblioteca estándar como email.py, json.py o typing.py. Cambia el nombre del archivo o directorio por uno específico del proyecto y, a continuación, actualiza las importaciones que hacían referencia a ese módulo local. Evita simplemente renombrarlo con otro nombre común de paquete o de la biblioteca estándar.

Si el archivo en conflicto es un módulo intencional del proyecto, consérvalo pero asígnale un nombre distintivo e impórtalo a través de la estructura de paquetes de tu proyecto. Un archivo de proyecto que coincide casualmente con el nombre de un paquete de terceros es especialmente propenso a causar importaciones parciales confusas o errores sobre atributos inexistentes.

Tras cambiar el nombre, elimina únicamente el directorio __pycache__ correspondiente si queda alguno junto al archivo antiguo. Normalmente, Python comprueba los tiempos de modificación de los archivos fuente y actualiza las cachés de bytecode de forma automática; eliminar la caché correspondiente es un paso de limpieza, no un sustituto de la resolución del conflicto de nombres. Documentación sobre módulos y bytecode de Python

3. Asegurarse de que el paquete pertenece al Python que ejecutas

En macOS, es común tener más de una instalación de Python o entorno de proyecto. El ejecutable mostrado como sys.executable es el intérprete detrás del comando que acabas de ejecutar. Instala los paquetes a través de ese intérprete para que pip y Python no apunten accidentalmente a entornos diferentes:

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

Utiliza el nombre de distribución del paquete con pip show y su nombre de importación con Python. Pueden diferir; por ejemplo, Pillow se importa habitualmente como PIL. Un resultado de "package not found" en pip show significa que esa distribución no está instalada para el intérprete utilizado por ese comando.

Para un entorno específico del proyecto, crea y activa un entorno virtual desde el directorio del proyecto y, a continuación, instala la dependencia allí:

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

Con el entorno activo, python debería resolverse a su intérprete. El último comando imprime la ruta real del archivo cargado; comprueba que se encuentre bajo .venv en lugar del nivel superior de tu proyecto. Los entornos virtuales aíslan los paquetes del proyecto de otros entornos y se crean con python -m venv. Documentación de venv de Python

4. Comprobar las anulaciones de rutas y volver a ejecutar limpiamente

Si el módulo aún se resuelve en una ubicación inesperada, inspecciona la ruta de búsqueda de Python y cualquier anulación mediante PYTHONPATH:

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

sys.path se inicializa utilizando PYTHONPATH y valores predeterminados dependientes de la instalación; en invocaciones comunes, Python también antepone el directorio del script o el directorio de trabajo actual. Elimina una configuración no deseada de PYTHONPATH de la shell actual con unset PYTHONPATH y luego vuelve a ejecutar el diagnóstico. En el caso de configuraciones persistentes, inspecciona el archivo de inicio de la shell donde se configuró y elimina o corrige esa exportación. Documentación de sys.path de Python

Reinicia el proceso de Python después de renombrar archivos o cambiar de entorno: un intérprete que ya se encuentra en ejecución puede retener en memoria los módulos que ha importado. Luego, repite la comprobación de origen y ejecuta el comando o la aplicación de la misma forma en que lo haces normalmente. Si el origen es correcto pero la importación sigue fallando, lee el traceback completo; puede que identifique una dependencia faltante o un error generado mientras el paquete se carga, en lugar de una colisión de nombres.

Fuentes