ImportError: cannot import name — causas y solución en Python

Python te detiene con algo como esto:

ImportError: cannot import name 'algo' from 'mi_modulo'

Es distinto del ModuleNotFoundError. Aquí Python sí encontró el módulo —existe—, pero no encuentra dentro de él el nombre que intentas importar. El módulo está, el nombre no. Eso acota mucho el problema, y hay tres causas típicas. Vamos por ellas.

Causa 1: el nombre está mal escrito o no existe

La más simple. Intentas importar algo que en el módulo se llama distinto, o que no está.

# en utilidades.py existe la función "calcular_total"
from utilidades import calcular_Total   # mayúscula de más → ImportError

Python distingue mayúsculas de minúsculas, así que calcular_Total y calcular_total son cosas distintas. La solución es revisar el módulo de origen y confirmar el nombre exacto. Abre utilidades.py y verifica cómo se llama de verdad la función o clase.

Un truco: si no recuerdas qué contiene el módulo, en una terminal de Python:

import utilidades
print(dir(utilidades))   # lista todo lo que el módulo expone

Eso te muestra los nombres reales disponibles.

Causa 2: importación circular (la traicionera)

Esta es la causa que hace perder horas. Ocurre cuando dos archivos se importan mutuamente, directa o indirectamente.

# archivo: modelos.py
from servicios import procesar

# archivo: servicios.py
from modelos import Usuario

Cuando Python carga modelos.py, este intenta importar de servicios.py, que a su vez intenta importar de modelos.py — pero modelos.py todavía no terminó de cargarse, así que el nombre que busca aún no existe. Resultado: ImportError, aunque todo “esté bien escrito”.

Es traicionera porque el código se ve correcto; el problema es el orden de carga, no un typo.

Hay varias formas de romper el círculo:

Mover la importación dentro de la función que la usa, en lugar de ponerla arriba del archivo. Así se importa solo cuando se ejecuta esa función, no al cargar el módulo:

# servicios.py
def procesar():
    from modelos import Usuario   # importación local, dentro de la función
    # ...usar Usuario...

Reorganizar el código para eliminar la dependencia mutua: a menudo, lo que ambos necesitan puede moverse a un tercer archivo del que ambos importen, sin que se importen entre sí.

La importación local es el arreglo rápido; reorganizar es el arreglo de fondo. Para salir del paso, la importación dentro de la función casi siempre funciona.

Causa 3: un archivo tuyo tapa a una librería

Parecido al caso del ModuleNotFoundError: si nombraste un archivo tuyo igual que una librería conocida, Python importa el tuyo y no encuentra dentro lo que esperaba de la librería real.

# tienes un archivo llamado email.py en tu carpeta
from email.mime.text import MIMEText   # importa TU email.py, no el de Python → ImportError

Tu email.py no tiene mime.text, así que falla. La solución: renombra tu archivo (email.py → mi_email.py) y borra la carpeta __pycache__ de esa carpeta, que puede guardar rastros del archivo viejo.

El diagnóstico en tres pasos

Cuando aparezca cannot import name, recórrelas en orden:

1. ¿El nombre está bien escrito y existe? Abre el módulo de origen y confirma el nombre exacto (o usa dir()).
2. ¿Hay importación circular? Mira si los archivos involucrados se importan entre sí. Si es así, mueve la importación dentro de la función o reorganiza.
3. ¿Un archivo tuyo se llama como una librería? Renómbralo y limpia __pycache__.

La clave que lo desmitifica: a diferencia del ModuleNotFoundError, aquí el módulo existe; el problema es qué hay dentro o en qué orden se carga. Con eso en mente, las tres causas se diagnostican rápido.

---

¿Tu caso es una importación circular enredada entre varios archivos y no logras desenredarla? Escríbeme desde contacto con la estructura de tus imports y lo vemos.