ModuleNotFoundError: No module named — las 4 causas reales

Ejecutas tu script y Python te corta con esto:

ModuleNotFoundError: No module named 'requests'

(o pandas, o flask, o el que sea). El primer instinto es correr a instalar el paquete. A veces funciona. Pero cuando lo instalas y el error sigue apareciendo, es porque la causa era otra. Hay cuatro escenarios distintos detrás de este mensaje, y vale la pena reconocerlos porque la solución cambia en cada uno.

Los vemos en orden de probabilidad, del más común al más traicionero.

Causa 1: el paquete no está instalado

La obvia, y la más frecuente. Python no encuentra el módulo porque, simplemente, no está en tu entorno. La solución:

pip install requests

Si eso lo resuelve, listo, no sigas leyendo. Pero si instalaste el paquete y el error persiste, no pierdas tiempo reinstalándolo una y otra vez: la causa es una de las siguientes tres. Ahí es donde la gente se atasca.

Causa 2: instalaste en un entorno y ejecutas en otro

Esta es la causa nº1 del “pero si ya lo instalé”. Tu computadora puede tener varias instalaciones de Python a la vez —la del sistema, la que instalaste tú, la de un entorno virtual— y cada una tiene sus propios paquetes. Instalas requests en una, ejecutas el script con otra, y esa otra no lo tiene.

La forma de verificar que estás en el mismo lado en los dos comandos es preguntarle a Python directamente:

python -c "import sys; print(sys.executable)"

Eso te dice exactamente qué Python está corriendo. Y luego instala usando ese mismo Python, no un pip suelto:

python -m pip install requests

El truco del python -m pip en vez de solo pip es clave: garantiza que instalas en el mismo Python con el que ejecutas, porque usas el mismo comando en ambos casos. Es el hábito que te ahorra este error para siempre.

Causa 3: olvidaste activar el entorno virtual

Muy relacionada con la anterior, pero merece su propia mención porque es un despiste diario. Creaste un entorno virtual, instalaste ahí tus paquetes, pero abriste una terminal nueva y olvidaste activarlo. Sin el entorno activo, Python usa la instalación global, que no tiene tus paquetes.

Se reconoce fácil: cuando el entorno está activo, verás su nombre entre paréntesis al inicio de la línea de la terminal, así:

(venv) C:\Users\tu\proyecto>

Si no ves ese (venv), actívalo:

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

Y recién entonces ejecuta tu script. Regla mental: si abriste una terminal nueva, lo primero es activar el entorno.

Causa 4: tu propio archivo se llama como el módulo

Esta es la traicionera, la que puede hacerte perder una hora porque el paquete sí está instalado y el entorno sí es el correcto. El problema es que nombraste un archivo tuyo igual que el módulo que intentas importar.

Si tienes un archivo llamado random.py en tu carpeta y escribes import random, Python encuentra primero tu archivo en vez de la librería estándar. El módulo real queda tapado por el tuyo. Lo mismo pasa con email.py, json.py, math.py, o incluso requests.py.

Hay una variante aún más sutil: un archivo .pyc viejo o una carpeta __pycache__ que quedó de un archivo que ya borraste, pero cuyo rastro sigue confundiendo la importación.

La solución: revisa que ningún archivo tuyo tenga el nombre de un módulo conocido. Si encuentras el culpable, renómbralo (por ejemplo random.py → mi_random.py) y borra la carpeta __pycache__ de esa carpeta. Al volver a ejecutar, Python encontrará el módulo verdadero.

El diagnóstico en 30 segundos

Cuando te aparezca el error, recórrelas en este orden y lo resuelves casi siempre a la primera:

1. ¿Lo instalaste? → python -m pip install nombre
2. ¿Instalaste y sigue? → verifica el intérprete con sys.executable e instala con python -m pip
3. ¿Usas entorno virtual? → confirma que veas (venv) en la terminal
4. ¿Todo lo anterior está bien? → busca un archivo tuyo con el nombre del módulo

Las cuatro cubren prácticamente todos los casos. El ModuleNotFoundError asusta al principio, pero una vez que sabes que son cuatro sospechosos y no uno, deja de ser un misterio.

---

¿Te apareció este error en un caso que no encaja en estos cuatro —dentro de Docker, en un notebook de Jupyter, al importar tu propio paquete? Escríbeme desde contacto y lo sumamos al artículo.