Se o Python importar um arquivo do seu projeto em vez do pacote instalado, primeiro identifique o arquivo que o Python está carregando. No macOS, verifique o interpretador ativo, o caminho do módulo importado e quaisquer arquivos ou pastas do projeto com o mesmo nome. Renomeie o arquivo local conflitante, remova o cache de bytecode desatualizado, se necessário, e execute o projeto com o ambiente Python pretendido.

1. Verifique qual Python e módulo estão em uso

No Terminal, acesse a pasta do projeto e solicite ao Python que informe a origem do módulo. Substitua requests pelo nome da importação que está falhando; por exemplo, um pacote instalado como Pillow é importado como PIL.

cd "/path/to/your/project"
command -v python3
python3 -c 'import sys, importlib.util; name = "requests"; print("Python:", sys.executable); print("Module:", importlib.util.find_spec(name))'

Um resultado com um origin dentro do diretório do seu projeto, como .../requests.py, indica um arquivo local que está causando sombreamento (shadowing). O Python coloca o diretório do script ou o diretório de trabalho atual no início do seu caminho de busca, de modo que um módulo local de mesmo nome pode ter precedência sobre um pacote instalado. Documentação do caminho de busca de módulos do Python

Se o comando retornar None, esse interpretador não consegue encontrar o módulo por esse nome. Se mostrar um local em site-packages, o conflito pode estar em outro lugar: seu aplicativo pode iniciar um interpretador diferente, o nome de importação pode ser diferente do nome de instalação do pacote ou o erro pode ocorrer dentro de uma dependência do pacote.

2. Encontre e renomeie o conflito local

Procure no projeto por um arquivo com o nome da importação, como requests.py, ou por um diretório com esse nome. Verifique também nomes comuns da biblioteca padrão, como email.py, json.py ou typing.py. Renomeie o arquivo ou diretório para um nome específico do projeto e, em seguida, atualize todas as importações que faziam referência a esse módulo local. Evite apenas renomeá-lo para outro nome comum de pacote ou da biblioteca padrão.

Se o arquivo conflitante for um módulo intencional do projeto, mantenha-o, mas atribua-lhe um nome diferenciado e importe-o por meio da estrutura de pacotes do seu projeto. Um arquivo de projeto que por acaso compartilha o nome de um pacote de terceiros tem grande probabilidade de causar importações parciais confusas ou erros sobre atributos ausentes.

Após renomear, remova apenas o diretório __pycache__ correspondente, se houver um restante ao lado do arquivo antigo. O Python normalmente verifica as datas de modificação dos arquivos-fonte e atualiza os caches de bytecode automaticamente; excluir o cache correspondente é uma etapa de limpeza, não um substituto para resolver o conflito de nomes. Documentação de módulos e bytecode do Python

3. Certifique-se de que o pacote pertence ao Python em execução

No macOS, é comum ter mais de uma instalação do Python ou ambiente de projeto. O executável exibido como sys.executable é o interpretador por trás do comando que você acabou de executar. Instale pacotes por meio desse interpretador para que o pip e o Python não apontem acidentalmente para ambientes diferentes:

python3 -m pip show requests
python3 -m pip install requests

Use o nome de distribuição do pacote com pip show e seu nome de importação com o Python. Eles podem ser diferentes; por exemplo, o Pillow é normalmente importado como PIL. O resultado "package not found" retornado pelo pip show significa que essa distribuição não está instalada para o interpretador usado por esse comando.

Para um ambiente específico do projeto, crie e ative um ambiente virtual a partir do diretório do projeto e, em seguida, instale a dependência nele:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -c 'import requests; print(requests.__file__)'

Com o ambiente ativo, python deve apontar para o seu interpretador. O comando final exibe o caminho real do arquivo carregado; certifique-se de que ele esteja dentro de .venv e não na raiz do seu projeto. Ambientes virtuais isolam os pacotes do projeto de outros ambientes e são criados com python -m venv. Documentação do venv do Python

4. Verifique substituições de caminho e execute novamente de forma limpa

Se o módulo ainda apontar para um local inesperado, inspecione o caminho de busca do Python e qualquer substituição de PYTHONPATH:

python -c 'import os, sys; print("PYTHONPATH:", os.environ.get("PYTHONPATH")); print("sys.path:"); print("\n".join(sys.path))'

sys.path é inicializado usando PYTHONPATH e padrões que dependem da instalação; em invocações comuns, o Python também adiciona o diretório do script ou o diretório de trabalho atual no início. Remova uma configuração não intencional de PYTHONPATH do shell atual com unset PYTHONPATH e execute o diagnóstico novamente. Para configurações persistentes, inspecione o arquivo de inicialização do shell onde ela foi definida e remova ou corrija essa exportação. Documentação do sys.path do Python

Reinicie o processo do Python após renomear arquivos ou alterar ambientes: um interpretador já em execução pode reter na memória os módulos importados. Em seguida, repita a verificação de origem e execute o comando ou aplicativo da mesma forma que faz habitualmente. Se a origem estiver correta, mas a importação ainda falhar, leia o traceback completo; ele pode identificar uma dependência ausente ou um erro gerado enquanto o pacote é carregado, em vez de um conflito de nomes.

Fontes