Cómo corregir ModuleNotFoundError en Python

El error ModuleNotFoundError en Python aparece cuando el intérprete no consigue localizar el módulo solicitado. Puede ocurrir porque el paquete no está instalado, el nombre está mal escrito, el editor usa otro intérprete, el proyecto tiene una estructura incorrecta o un archivo se ejecuta desde la carpeta equivocada.

Instalar el paquete otra vez no siempre resuelve el problema. Antes de modificar el entorno, debes comprobar qué Python está ejecutando el código, dónde busca módulos y cuál es el nombre correcto de la distribución.

Ejemplo básico

import requests_not_real

Python puede mostrar:

ModuleNotFoundError: No module named 'requests_not_real'

La última línea indica el módulo que no fue encontrado. El traceback completo muestra desde qué archivo se intentó importar.

La documentación de ModuleNotFoundError explica que esta excepción es una subclase de ImportError.

Comprobar la ortografía

Revisa mayúsculas, guiones bajos y el nombre utilizado por la biblioteca:

# Incorrecto
import request

# Correcto
import requests

El nombre del paquete instalado puede ser diferente del nombre importado. Por ejemplo:

python -m pip install beautifulsoup4

from bs4 import BeautifulSoup

Comprobar qué intérprete se está utilizando

import sys

print(sys.executable)
print(sys.version)

Después compara con el terminal:

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

El ejecutable mostrado por pip debe pertenecer al mismo entorno que ejecuta el script. La guía de venv en Python explica cómo crear un entorno aislado y seleccionarlo en el editor.

Instalar con python -m pip

python -m pip install requests

Este formato vincula pip al intérprete indicado por python. Utilizar solamente pip install puede activar otro ejecutable disponible en PATH.

La guía oficial de instalación de paquetes describe pip, entornos virtuales y nombres de distribuciones.

Confirmar que el paquete está instalado

python -m pip show requests
python -m pip list
python -m pip check

pip show revela la ubicación de la instalación. pip check detecta dependencias incompatibles o ausentes.

Seleccionar el intérprete en VS Code

Abre la paleta de comandos y ejecuta Python: Select Interpreter. Elige el entorno del proyecto, abre un terminal nuevo y vuelve a ejecutar:

python -c "import requests; print(requests.__file__)"

La guía de instalación y configuración de VS Code muestra cómo seleccionar intérpretes y trabajar con .venv.

Revisar sys.path

import sys

for location in sys.path:
    print(location)

Python busca módulos en estas ubicaciones. La carpeta del proyecto, la biblioteca estándar y los paquetes del entorno suelen aparecer. No añadas rutas arbitrarias de forma permanente antes de entender por qué la estructura no funciona.

Comprobar el directorio actual

from pathlib import Path

print(Path.cwd())
print(Path(__file__).resolve())

El directorio actual puede ser distinto de la carpeta del script. Esto afecta archivos y algunos imports en proyectos mal estructurados.

La guía de pathlib en Python explica rutas absolutas, padres y resolución de archivos.

Organizar un paquete local

shop/
├── pyproject.toml
├── src/
│   └── shop/
│       ├── __init__.py
│       ├── products.py
│       └── reports.py
└── tests/

Desde reports.py, un import interno puede ser:

from shop.products import calculate_total

Instala el proyecto en modo editable durante el desarrollo:

python -m pip install -e .

La guía de módulos y paquetes en Python explica __init__.py, imports absolutos y la estructura src.

No ejecutar un archivo interno desde la carpeta equivocada

Este comando puede romper el contexto del paquete:

python shop/reports.py

Desde la raíz, utiliza:

python -m shop.reports

-m permite que Python resuelva el módulo dentro de su paquete.

Comprobar archivos con nombres conflictivos

Un archivo local llamado requests.py no suele producir ModuleNotFoundError para requests, pero puede romper submódulos:

project/
├── requests.py
└── main.py

Renombra el archivo y elimina __pycache__. Evita nombres como json.py, socket.py, typing.py o email.py.

Notebooks y entornos diferentes

Jupyter puede utilizar un kernel distinto del terminal. Comprueba:

import sys
print(sys.executable)

Instala el paquete en ese ejecutable o registra el entorno como kernel. Reinicia el kernel después de instalar.

Docker y despliegues

Un paquete presente en tu ordenador puede faltar en la imagen:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN python -m pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]

Asegúrate de que el archivo de dependencias está actualizado y que la instalación ocurre antes de ejecutar la aplicación.

Dependencias opcionales

try:
    import pandas
except ModuleNotFoundError as error:
    raise RuntimeError(
        "Instala la opción de análisis con: "
        "python -m pip install app[data]"
    ) from error

Captura la excepción solamente cuando el módulo sea realmente opcional. No ocultes una dependencia obligatoria ausente.

Utilizar importlib para diagnosticar

import importlib.util

module_name = "requests"
spec = importlib.util.find_spec(module_name)

if spec is None:
    print("No encontrado")
else:
    print("Origen:", spec.origin)

La referencia de importlib documenta herramientas para inspeccionar e implementar imports.

Script completo de diagnóstico

import importlib.util
import sys
from pathlib import Path

module_name = "requests"

print("Python:", sys.executable)
print("Versión:", sys.version)
print("Directorio:", Path.cwd())

spec = importlib.util.find_spec(module_name)

if spec is None:
    print(f"{module_name}: no encontrado")
else:
    print(f"{module_name}: {spec.origin}")

Orden recomendado para resolverlo

1. Comprueba la ortografía del import.
2. Imprime sys.executable.
3. Ejecuta python -m pip show PAQUETE.
4. Confirma el intérprete del editor o kernel.
5. Revisa el directorio y sys.path.
6. Comprueba la estructura del paquete local.
7. Busca archivos con nombres conflictivos.
8. Reinicia el proceso después de instalar o renombrar.

La guía de try y except en Python ayuda a distinguir entre manejar una dependencia opcional y ocultar un error de configuración.

Errores frecuentes

• Instalar con un pip perteneciente a otro Python.
• Escribir el nombre de la distribución en lugar del import correcto.
• Ejecutar un archivo interno directamente.
• Modificar sys.path sin corregir la estructura.
• No reiniciar un notebook o servidor.
• Olvidar dependencias en Docker o producción.
• Crear un archivo local con el nombre de una biblioteca.

Conclusión

ModuleNotFoundError se resuelve identificando el intérprete, la ubicación de la instalación y la ruta de búsqueda. Verifica primero el nombre y sys.executable; después revisa pip, el entorno, la estructura del proyecto y la forma de ejecución. Este orden evita instalaciones repetidas y cambios innecesarios.