Python ModuleNotFoundError: como descobrir onde o pacote foi instalado e corrigir o ambiente

Você executa pip install, recebe uma mensagem de sucesso e, na linha seguinte, o Python responde ModuleNotFoundError: No module named .... Na maior parte das vezes, o pacote não desapareceu: ele foi instalado para outro interpretador, outro ambiente virtual ou outro usuário. Também pode existir diferença entre o nome publicado no índice e o nome usado no import.

Este guia propõe um diagnóstico determinístico. Em vez de reinstalar tudo ou alterar PYTHONPATH às cegas, você identificará qual Python executa o programa, qual pip pertence a ele, onde os pacotes ficam, como sys.path é formado e quando a falha está na estrutura do próprio projeto.

Legenda: o pacote só será importado quando instalação e execução apontarem para o mesmo ambiente.

O erro informa o nome importado, não necessariamente o pacote instalado

Considere:

from PIL import Image

O projeto distribuído chama-se Pillow, mas o módulo importado é PIL. O inverso também ocorre: um pacote pode fornecer vários módulos. Portanto, pip install PIL não é uma conclusão válida a partir da mensagem. Consulte a documentação oficial do projeto e confirme o comando correto.

Há ainda três erros parecidos:

• ModuleNotFoundError: o mecanismo de importação não encontrou o módulo solicitado;
• ImportError: o módulo pode ter sido encontrado, mas um nome ou dependência não pôde ser importado;
• erro dentro do módulo: o arquivo foi localizado e executado, porém falhou durante sua inicialização.

Leia o traceback desde o fim e preserve a primeira causa relevante. Instalar o nome que aparece em qualquer linha pode criar dependências desnecessárias.

Descubra qual Python executa o código

No mesmo terminal em que ocorre a falha, execute:

python -c "import sys; print(sys.executable); print(sys.version)"
python -m pip --version

No Windows, o lançador também ajuda:

py -0p
py -3 -c "import sys; print(sys.executable)"
py -3 -m pip --version

Compare os caminhos. A saída de python -m pip --version informa a localização do pip e a versão de Python associada. Usar python -m pip é mais seguro que chamar pip isoladamente porque o módulo é carregado pelo interpretador escolhido naquele comando.

Se o programa roda por IDE, notebook, serviço ou tarefa agendada, o terminal pode não representar o ambiente real. Imprima temporariamente sys.executable dentro da aplicação. Depois remova o diagnóstico ou envie-o a um log sem dados pessoais.

Verifique se o pacote existe nesse ambiente

Use o mesmo interpretador:

python -m pip show requests
python -m pip list
python -m pip check

pip show apresenta versão e Location. pip check procura dependências instaladas com requisitos incompatíveis ou ausentes. Se show não encontra o pacote, ele não está instalado naquele ambiente, mesmo que outro pip diga o contrário.

Para confirmar sem executar o módulo, use importlib.util.find_spec:

python -c "import importlib.util; print(importlib.util.find_spec('requests'))"

Um resultado None indica que o importador não localizou o nome. Um objeto ModuleSpec mostra a origem prevista. Esse teste é útil quando importar o pacote dispara efeitos colaterais ou falha por outra dependência.

Crie um ambiente virtual reproduzível

Um ambiente virtual separa os pacotes do projeto das instalações globais. A documentação do venv explica que ele cria um ambiente com seu próprio executável e diretório de pacotes.

Linux e macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install requests
python -c "import requests; print(requests.__version__)"

Windows PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install requests
python -c "import requests; print(requests.__version__)"

Ativação é conveniência, não magia. Você pode chamar o executável diretamente: .venv/bin/python ou .venv\Scripts\python.exe. Isso é especialmente útil em tarefas agendadas e serviços, nos quais scripts de ativação podem não rodar.

Não versione a pasta .venv; registre dependências em requirements.txt, pyproject.toml ou no formato adotado pelo projeto. Ambientes virtuais são recriáveis e contêm caminhos específicos da máquina.

Entenda sys.path sem modificá-lo às cegas

O Python procura módulos nos diretórios de sys.path. Inspecione:

python -c "import sys; print('\n'.join(sys.path))"
python -m site

A lista inclui o diretório do script, entradas do ambiente, biblioteca padrão e diretórios site-packages. A documentação do sistema de importação detalha os localizadores e carregadores envolvidos.

Evite inserir caminhos absolutos no código:

# Evite este curativo:
import sys
sys.path.append("C:/Users/alguem/projeto")

Esse caminho funciona em uma máquina e quebra em outra. Corrija a forma de executar o pacote, instale o projeto em modo editável ou organize os módulos dentro de uma estrutura reconhecida.

Legenda: o diagnóstico compara o nome importado com cada origem de módulos do interpretador ativo.

Quando o problema está no próprio projeto

Crie este laboratório:

meu-projeto/
├── pyproject.toml
├── src/
│   └── calculadora/
│       ├── __init__.py
│       └── operacoes.py
└── tests/
    └── test_operacoes.py

src/calculadora/operacoes.py:

def somar(a, b):
    return a + b

pyproject.toml mínimo:

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

[project]
name = "calculadora-demo"
version = "0.1.0"
requires-python = ">=3.10"

Na raiz, execute:

python -m pip install -e .
python -c "from calculadora.operacoes import somar; print(somar(2, 3))"

O modo editável registra o projeto no ambiente e mantém o código apontando para a pasta de desenvolvimento. Executar um arquivo isolado de dentro de tests pode alterar o primeiro item de sys.path e produzir um erro que não ocorre com o pacote instalado.

Arquivos que escondem bibliotecas

Um arquivo local chamado requests.py, json.py, typing.py ou email.py pode esconder o pacote real ou a biblioteca padrão. O Python encontra o arquivo local primeiro e importa a coisa errada. Às vezes a mensagem vira “cannot import name”; em outros casos, surge importação circular.

Descubra a origem:

python -c "import json; print(json.__file__)"

Se o caminho aponta para seu projeto quando deveria apontar para a biblioteca padrão, renomeie o arquivo e remova caches __pycache__ gerados para o nome antigo. Não use nomes de bibliotecas populares para scripts de teste.

Também verifique uma pasta com o mesmo nome do módulo. O conflito pode estar em qualquer entrada anterior de sys.path, não apenas no diretório atual.

Jupyter e IDE: o kernel pode ser outro Python

No notebook, !pip install pacote pode chamar o pip do shell, enquanto o kernel usa outro interpretador. Prefira instalar pelo próprio executável do kernel:

import sys
print(sys.executable)
!{sys.executable} -m pip install requests

Após instalar extensões nativas ou alterar componentes carregados, reinicie o kernel. Para ambientes permanentes, registre o kernel correspondente e selecione-o explicitamente na interface.

No VS Code, PyCharm ou outra IDE, confira o interpretador do projeto, não apenas o do terminal integrado. Dois terminais na mesma pasta podem ter ambientes ativados diferentes. Inclua no diagnóstico sys.executable, sys.prefix e sys.base_prefix; quando prefix difere de base_prefix, geralmente há ambiente virtual ativo.

Versão do Python e compatibilidade da plataforma

Um pacote pode estar instalado para Python 3.11, mas o programa roda em 3.12. Cada versão possui seu diretório site-packages, e extensões compiladas podem ser específicas do interpretador, sistema e arquitetura.

Confira:

python -c "import platform, sys; print(platform.platform()); print(platform.machine()); print(sys.version)"
python -m pip debug --verbose

Se o pacote não publica uma distribuição compatível, o erro de instalação costuma aparecer antes do import. Não baixe binários aleatórios para contornar isso. Procure uma versão suportada, instale as ferramentas de compilação indicadas pelo projeto ou escolha uma alternativa mantida.

Em sistemas que gerenciam o Python global, instalar com privilégios administrativos pode danificar pacotes do sistema. Prefira ambiente virtual e siga a orientação da distribuição.

requirements.txt, pyproject e instalação limpa

Depois de corrigir o ambiente, torne o resultado reproduzível. Um requirements.txt simples pode ser instalado com:

python -m pip install -r requirements.txt
python -m pip check

Projetos empacotados devem declarar dependências em pyproject.toml. Evite listar tudo que existe no computador; registre somente dependências do projeto e use ferramentas adequadas quando precisar bloquear versões transitivas.

Teste em um ambiente novo:

python -m venv .venv-teste
.venv-teste/bin/python -m pip install -e .
.venv-teste/bin/python -m pip check

No Windows, troque o caminho pelo executável em Scripts. Esse teste prova que o projeto não depende por acidente de um pacote global.

Execute pacotes com python -m

Um arquivo pode funcionar quando chamado da raiz e falhar quando executado por caminho. Suponha:

app/
├── relatorios/
│   ├── __init__.py
│   ├── gerar.py
│   └── formatos.py

Dentro de gerar.py, uma importação relativa pode ser válida no contexto do pacote:

from .formatos import criar_csv

Executar python relatorios/gerar.py trata o arquivo como script principal, sem o mesmo contexto de pacote. A forma correta, a partir da raiz, é:

python -m relatorios.gerar

Isso permite que o sistema de importação resolva relatorios como pacote. Não troque automaticamente a importação relativa por from formatos import ...; essa alteração pode funcionar por causa do diretório atual e voltar a falhar quando o projeto for instalado.

Também evite depender de os.getcwd() para localizar recursos. O diretório de trabalho é decidido por quem iniciou o processo. Para arquivos empacotados, use importlib.resources; para configuração externa, receba um caminho explícito e valide-o.

Em testes, execute a suíte a partir da raiz com a ferramenta configurada e o projeto instalado. Se cada teste manipula sys.path, a estrutura real não está sendo exercitada.

Instalação global, --user e ambientes gerenciados

pip install --user pacote grava no diretório do usuário, não no ambiente virtual. Alguns ambientes desativam o user site, e serviços executados com outra conta não enxergam os mesmos arquivos. Compare:

python -m site --user-site
python -c "import site; print(site.ENABLE_USER_SITE)"

Não misture instalação global, --user e .venv no mesmo diagnóstico. Escolha um ambiente, use seu executável e registre dependências. Em Linux distribuído pelo sistema, a instalação global pode ser marcada como externamente gerenciada; a resposta segura é criar um ambiente virtual, não substituir proteções do gerenciador.

Serviços e tarefas agendadas merecem atenção adicional. Eles podem usar usuário, pasta inicial e PATH diferentes do login interativo. Configure o caminho absoluto do Python da .venv, o diretório de trabalho e as variáveis necessárias. Registre somente nomes e caminhos não sensíveis.

Se um pacote foi instalado com privilégio administrativo, mas a aplicação comum não o encontra, não repita a instalação elevada. Descubra qual interpretador recebeu o pacote e recrie o ambiente do projeto com permissões normais. Essa separação reduz conflitos e torna a implantação reproduzível.

Documente o comando exato usado para iniciar a aplicação. “Rodar o Python” pode significar o lançador do sistema, o executável da IDE, um kernel ou o binário da .venv. Uma linha de inicialização explícita elimina essa ambiguidade e permite que outra pessoa reproduza o mesmo ambiente sem depender da configuração pessoal da máquina original.

Um script de diagnóstico que não altera nada

Salve como diagnostico_import.py:

import importlib.util
import site
import sys

nome = sys.argv[1] if len(sys.argv) > 1 else "requests"
spec = importlib.util.find_spec(nome)

print("executavel:", sys.executable)
print("versao:", sys.version.split()[0])
print("prefixo:", sys.prefix)
print("base:", sys.base_prefix)
print("user_site:", site.getusersitepackages())
print("modulo:", nome)
print("encontrado:", bool(spec))
print("origem:", getattr(spec, "origin", None))

Execute python diagnostico_import.py requests. O script apenas consulta o ambiente; não instala, remove ou importa o pacote. Anexe a saída a um chamado após retirar nomes de usuário presentes em caminhos.

Para organizar experimentos, consulte a biblioteca de Python do IATechNerds. Se a análise envolver tabelas de versões ou inventário de máquinas, o iatnGrid ajuda a comparar planilhas localmente. O catálogo de ferramentas reúne os utilitários disponíveis.

Checklist para encerrar o ModuleNotFoundError

• o nome de distribuição e o nome importado foram confirmados;
• sys.executable identifica o Python real da aplicação;
• python -m pip --version aponta para o mesmo ambiente;
• pip show e find_spec foram consultados;
• o ambiente virtual foi criado ou selecionado corretamente;
• não há arquivo local escondendo a biblioteca;
• IDE, kernel, serviço e terminal usam o interpretador esperado;
• a versão do Python e a plataforma são suportadas;
• dependências foram declaradas e testadas em ambiente limpo;
• nenhum caminho absoluto foi adicionado como curativo.

Documentação primária

• Python — sistema de importação
• Python — ambientes virtuais com venv
• Python — módulo site
• Python — importlib
• pip — guia de ambientes locais

Nota de produção

Rascunho autoral orientado à busca “Python ModuleNotFoundError mesmo após pip install”. Os comandos foram escritos para diagnóstico local e usam documentação primária do Python e do pip. A revisão humana deve executar os exemplos em Windows e em um sistema Unix, confirmar os caminhos da versão suportada e revisar a voz editorial antes da publicação.

Camada extra: como tomar uma decisão melhor neste cenário

Para levar Python ModuleNotFoundError: como descobrir onde o pacote foi instalado e corrigir o ambiente além de uma receita de passos, vale transformar o procedimento em um pequeno método: observar, isolar, alterar uma variável e conferir o resultado.

Você executa `pip install`, recebe uma mensagem de sucesso e, na linha seguinte, o Python responde **ModuleNotFoundError: No module named ...**. Na maior parte das vezes, o pacote não desapareceu: ele foi instalado para outro interpretador, A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Depure por camadas, não por palpites

Para Python, pip, venv, ModuleNotFoundError, uma mensagem de erro geralmente descreve o ponto em que a execução falhou, não necessariamente a causa inicial. Reduza o cenário até a menor reprodução possível e verifique ambiente, entrada, configuração, dependências e estado antes de alterar o código principal. Se duas mudanças são feitas ao mesmo tempo, você perde a capacidade de saber qual delas resolveu — ou qual criou o próximo defeito.

Registre versão da ferramenta, comando executado, trecho mínimo da entrada e saída observada. Em seguida, faça uma mudança reversível e repita exatamente o mesmo teste. Essa disciplina parece lenta durante cinco minutos e economiza horas quando o problema reaparece em outra máquina ou no ambiente de produção.

Matriz de diagnóstico

Camada	Sinal típico	Teste útil
Ambiente	Funciona em uma máquina e falha em outra	Comparar versões e variáveis
Entrada	Falha só com certos dados	Caso mínimo reproduzível
Estado	Falha intermitente	Logs, concorrência e sequência
Integração	Componente isolado funciona	Inspecionar fronteiras e contratos

Antes de considerar resolvido

Rode o caso que falhava, um caso normal e um caso-limite. Confirme logs limpos, ausência de regressão e comportamento previsível após reiniciar o processo. Se a correção depende de “rodar de novo até funcionar”, o diagnóstico ainda não terminou.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.