Cómo corregir ImportError en Python paso a paso

El error ImportError en Python aparece cuando el intérprete encuentra un módulo, pero no puede importar el nombre solicitado o completar correctamente su carga. Suele estar relacionado con nombres incorrectos, archivos que ocultan bibliotecas, imports circulares, versiones incompatibles o una estructura de proyecto confusa.

Este error no es exactamente igual a ModuleNotFoundError. El segundo indica normalmente que Python no encontró el módulo. ImportError suele indicar que el módulo existe, pero el objeto solicitado no está disponible o la importación quedó incompleta.

Leer el mensaje completo

from math import square_root

El módulo math existe, pero no contiene un nombre llamado square_root. Python puede mostrar:

ImportError: cannot import name 'square_root' from 'math'

La solución es comprobar el nombre correcto:

from math import sqrt

print(sqrt(81))

La referencia oficial sobre el sistema de importación de Python explica cómo se localizan, crean y cargan los módulos.

Diferencia entre ImportError y ModuleNotFoundError

import package_that_does_not_exist

Este caso produce normalmente ModuleNotFoundError. En cambio:

from existing_module import missing_name

Puede producir ImportError. Ambas excepciones pertenecen a la misma familia, pero el diagnóstico es diferente.

La guía de errores comunes de Python muestra cómo leer tracebacks y localizar el archivo que originó el problema.

Comprobar errores de escritura

Revisa mayúsculas, guiones bajos y el nombre exportado:

# helpers.py

def calculate_total(values):
    return sum(values)

# main.py
from helpers import calculate_total

print(calculate_total([10, 20, 30]))

En sistemas que distinguen mayúsculas y minúsculas, Helpers.py y helpers.py pueden ser archivos diferentes.

Inspeccionar los nombres disponibles

import helpers

print(dir(helpers))
print(helpers.__file__)

dir() muestra nombres accesibles. __file__ revela qué archivo se importó realmente. Esta comprobación es importante cuando existen varios módulos con el mismo nombre.

Evitar que un archivo oculte una biblioteca

Un archivo local llamado requests.py, json.py, random.py o typing.py puede ocultar la biblioteca verdadera:

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

Cuando main.py ejecuta import random, Python puede cargar el archivo local. Renómbralo y elimina las carpetas __pycache__ relacionadas.

La guía de módulos y paquetes en Python explica rutas de importación, __init__.py y organización de proyectos.

Diagnosticar un import circular

Existe una dependencia circular cuando dos módulos se importan mutuamente:

# users.py
from orders import create_order


def create_user():
    return "user"

# orders.py
from users import create_user


def create_order():
    return create_user()

Python comienza a cargar users, entra en orders y vuelve a solicitar users antes de que el primer archivo haya terminado. El módulo queda parcialmente inicializado.

Una solución consiste en mover la funcionalidad compartida a un tercer archivo:

project/
├── common.py
├── users.py
└── orders.py

Otra opción es reducir la dependencia entre capas o importar localmente dentro de una función cuando exista una razón clara.

Usar imports absolutos coherentes

Dentro de un paquete, un import absoluto comienza en el nombre principal:

from store.products import calculate_price

Un import relativo utiliza puntos:

from .products import calculate_price

No mezcles estilos sin comprender desde dónde se ejecuta el programa. Ejecutar un archivo interno directamente puede romper imports relativos:

python -m store.reports

El modificador -m conserva el contexto del paquete.

Comprobar el intérprete y el entorno virtual

import sys

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

El editor, el terminal y el servidor deben utilizar el mismo intérprete. La guía de entornos virtuales con venv explica cómo crear un entorno por proyecto y seleccionar el Python correcto.

Comprobar la versión instalada

python -m pip show package-name
python -m pip list
python -m pip check

Un nombre puede existir en una versión nueva, pero no en la instalada. Consulta la documentación de la biblioteca y evita asumir que todos los entornos tienen la misma API.

La guía oficial de instalación de paquetes de Python explica pip, entornos y resolución de dependencias.

No instalar el nombre equivocado

El nombre utilizado en pip install puede ser diferente del import:

python -m pip install beautifulsoup4

from bs4 import BeautifulSoup

Consulta siempre la página oficial del proyecto. Evita instalar paquetes desconocidos solamente porque su nombre coincide con el error.

Revisar __init__.py

El archivo __init__.py puede volver a exportar nombres:

# store/__init__.py
from .products import Product

__all__ = ["Product"]

Un error dentro de este archivo puede impedir la importación de todo el paquete. Mantén sus efectos secundarios al mínimo.

Utilizar importlib para inspección

import importlib.util

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

if spec is None:
    print("Módulo no encontrado")
else:
    print(spec.origin)

Esto permite verificar el origen sin ejecutar toda la lógica del paquete.

Limpiar cachés después de renombrar

Cuando cambias nombres de archivos o paquetes, elimina __pycache__ y reinicia el intérprete, notebook o servidor. Un proceso activo puede conservar módulos en sys.modules.

Capturar ImportError de forma deliberada

Algunas aplicaciones admiten dependencias opcionales:

try:
    import orjson as json_backend
except ImportError:
    import json as json_backend

Este patrón es válido cuando existe una alternativa real. No captures la excepción para ocultar una instalación rota.

La guía de try y except en Python explica captura selectiva y encadenamiento.

Script de diagnóstico

import importlib.util
import sys
from pathlib import Path

module_name = "requests"

print("Python:", sys.executable)
print("Carpeta actual:", Path.cwd())
print("Primeras rutas:")

for path in sys.path[:5]:
    print(" -", path)

spec = importlib.util.find_spec(module_name)
print("Origen:", spec.origin if spec else "No encontrado")

La guía de pathlib en Python ayuda a revisar rutas sin concatenar texto manualmente.

Procedimiento recomendado

1. Lee la última línea y el traceback completo.
2. Comprueba el nombre solicitado.
3. Imprime module.__file__.
4. Busca archivos locales con el mismo nombre.
5. Revisa imports circulares.
6. Confirma sys.executable.
7. Comprueba versión y dependencias con pip.
8. Reinicia el proceso y limpia cachés.

Errores frecuentes

• Instalar paquetes repetidamente sin comprobar el intérprete.
• Nombrar un archivo igual que una biblioteca.
• Ejecutar directamente un módulo interno.
• Ocultar el error con un except ImportError amplio.
• Crear efectos secundarios durante la importación.
• Ignorar una dependencia circular.
• Editar sys.path de forma permanente para compensar una estructura incorrecta.

Conclusión

Para corregir ImportError, determina primero si el nombre existe, qué archivo se está cargando y si el módulo terminó de inicializarse. Después revisa estructura, dependencias, versión e intérprete. La mayoría de los casos se resuelve corrigiendo un nombre, renombrando un archivo conflictivo, eliminando una dependencia circular o seleccionando el entorno correcto.