Tecnología · GUÍA PRÁCTICA
¿pip dice instalado pero aparece ModuleNotFoundError? Prueba el intérprete y la ruta
Identifica el Python del proceso que falla, verifica su distribución, el nombre real de import y sys.path, y cierra solo con una importación limpia.
Una instalación correcta y un import fallido pueden ser ciertos si describen intérpretes, nombres o rutas diferentes.
Empieza dentro del proceso que falla, vincula cada comando a su Python absoluto y prueba metadata, nombres, resolución y origen del módulo.
Conserva el runtime que falla
Repite el comando exacto y guarda directorio y traceback. Con la misma ruta de lanzamiento imprime sys.executable, versión, prefix, base_prefix y sys.path. Terminal, IDE, notebook, servicio y shebang pueden elegir intérpretes distintos.
No empieces con sudo pip, --user, PYTHONPATH global ni copiando site-packages. La primera evidencia es el ejecutable absoluto informado por el proceso que falló.
Pregunta a ese intérprete por la distribución
Ejecuta /absolute/python -m pip show <distribution> y guarda Name, Version, Location y, si hace falta, --files. El éxito de otro pip no demuestra visibilidad aquí.
Si esa distribución falta, instala en el entorno previsto tras revisar el lock. Si Location no está en sys.path, investiga activación, user site, pyvenv.cfg, servicio o contenedor.
Separa distribución e import
pip usa un nombre de distribución e import usa un paquete importable. No hay relación obligatoria uno a uno; Pillow se importa como PIL.
Confirma documentación y archivos instalados; consulta packages_distributions() cuando ayude. No declares fallo de instalación por probar el nombre equivocado.
Explica la ruta en vez de parchearla
Python construye sys.path con script o directorio actual, variables, señales del ejecutable, configuración venv y site. Registra USER_SITE y ENABLE_USER_SITE con python -m site.
Un servicio puede desactivar user site, un IDE conservar un kernel viejo y un shebang apuntar a otro ejecutable. Repara el límite mínimo y evita parches globales.
Descarta shadowing y exige prueba final
Busca archivos o carpetas locales con el mismo nombre. Usa find_spec antes de importar y module.__file__ después para descartar shadowing.
Cierra solo cuando el mismo ejecutable ve Location, resuelve el import desde la ruta prevista, importa en proceso limpio y ejecuta el script o test original. Guarda toda la prueba.
