Como corrigir ImportError: cannot import name ao importar um módulo?

Como corrigir ImportError: cannot import name ao importar um módulo?

O erro ImportError: cannot import name 'X' from 'Y' acontece quando o Python não consegue localizar um nome específico dentro de um módulo. Isso pode ocorrer por diversas razões, como importações circulares, mudanças na estrutura do módulo ou erros no caminho de importação.

Exemplo do erro:

Suponha que temos um arquivo modulo.py com a seguinte estrutura:

# modulo.py
def funcao():
    return "Olá, mundo!"

Se tentarmos importar funcao da seguinte forma:

from modulo import funcao_errada
print(funcao_errada())

Receberemos o erro:

ImportError: cannot import name 'funcao_errada' from 'modulo'

Como resolver esse erro?

1. Verifique o nome correto da função/classe

Certifique-se de que o nome da função ou classe que está tentando importar realmente existe no módulo.

from modulo import funcao
print(funcao())

2. Evite importações circulares

Importações circulares ocorrem quando dois arquivos tentam importar um ao outro. Para corrigir:

• Mova a importação para dentro de uma função em vez de colocá-la no topo do arquivo.
• Verifique se há importações desnecessárias entre módulos.

3. Verifique se o módulo está no mesmo diretório

Se o módulo estiver em um diretório diferente, certifique-se de adicionar seu caminho ao sys.path:

import sys
sys.path.append("/caminho/para/o/modulo")

4. Use caminhos relativos para pacotes internos

Caso esteja trabalhando com pacotes internos, utilize importações relativas:

from .modulo import funcao

5. Reinicie o interpretador Python

Às vezes, a solução mais simples é reiniciar o ambiente Python para recarregar corretamente os módulos.

Seguindo essas etapas, é possível corrigir o erro ImportError: cannot import name e garantir que os módulos sejam importados corretamente no seu código.

O que causa ImportError e como evitá-lo

Os erros de importação em Python podem ser frustrantes, mas geralmente têm soluções simples. O ImportError ocorre quando um nome específico não é encontrado dentro de um módulo, o que pode acontecer por mudanças na estrutura do código ou por importações circulares. Com boas práticas de organização de módulos e conhecimento dos caminhos corretos, esse erro pode ser evitado.

Algumas aplicações:

• Importação correta de funções e classes entre módulos
• Melhor organização de código e estruturação de pacotes
• Redução de erros ao importar módulos personalizados

Dicas para quem está começando

• Verifique se a função ou classe existe no módulo antes de importar
• Evite importações circulares, reestruturando os módulos se necessário
• Reinicie o ambiente Python se encontrar erros inesperados
• Use importações relativas para pacotes internos

Compartilhe este tutorial