ModuleNotFoundError em Python: como corrigir

Para corrigir ModuleNotFoundError, descubra qual Python executa o código e instale a dependência nesse mesmo interpretador. Use import sys; print(sys.executable) no programa e python -m pip --version no terminal. Se o módulo for do próprio projeto, a correção pode ser executar com python -m pacote.modulo ou instalar o projeto — não baixar um pacote de nome parecido.

Esse erro costuma aparecer no primeiro projeto de automação: o tutorial manda instalar uma biblioteca, o terminal diz que deu certo, mas o VS Code continua mostrando No module named. O objetivo aqui é diagnosticar a causa, sem reinstalar o Python inteiro nem usar comandos administrativos às cegas.

O que significa No module named?

ModuleNotFoundError é uma subclasse de ImportError. Ela indica que o mecanismo de importação não encontrou um módulo solicitado. A mensagem pode mencionar o import que você escreveu ou uma dependência importada por outra biblioteca.

Exemplo de mensagem:

Traceback (most recent call last):
  File "relatorio.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

Leia o traceback completo. Se você importou biblioteca_a, mas a última linha cita biblioteca_b, investigue biblioteca_b e as dependências declaradas pela primeira. Não conclua que qualquer erro de import se resolve com pip install.

1. Confira o Python que realmente executa o script

Coloque este diagnóstico antes do import que falha, salve e rode pelo mesmo botão ou comando que produz o erro:

import sys

print("Executável:", sys.executable)
print("Versão:", sys.version)
print("Ambiente:", sys.prefix)
print("Instalação base:", sys.base_prefix)
print("Caminhos de importação:")
for caminho in sys.path:
    print(" ", repr(caminho))

Depois, no terminal:

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

Em Linux e macOS, se o comando disponível for python3, use python3 nos dois comandos. No Windows, py também pode selecionar um Python, mas confirme qual versão ele abre: não suponha que seja a mesma usada pela IDE.

O caminho de sys.executable no script deve corresponder ao Python que você usa para instalar. python -m pip --version mostra a localização do pip e a versão do Python associada. Um caminho global e outro dentro de .venv são uma pista forte de ambientes diferentes.

Em ambientes criados com venv, sys.prefix != sys.base_prefix indica que o interpretador está no ambiente virtual. Essa comparação não deve ser usada como teste universal de ambientes Conda; o caminho do executável continua sendo a verificação principal.

2. Instale com o Python do projeto, não com um pip solto

pip install requests depende de qual executável pip aparece primeiro no PATH. Já python -m pip install requests executa o pip associado ao comando python. A segunda forma reduz ambiguidades, mas ainda exige escolher o Python correto.

Para um projeto novo em Linux ou macOS:

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

No PowerShell, a partir da pasta do projeto:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install requests
.\.venv\Scripts\python.exe -m pip show requests
.\.venv\Scripts\python.exe -c "import requests; print(requests.__version__)"

Chamar o executável diretamente funciona sem ativar o ambiente e evita depender da política de execução de scripts do PowerShell. Depois de salvar seu programa como relatorio.py, execute-o com esse mesmo Python:

.venv/bin/python relatorio.py

No Windows, use .\.venv\Scripts\python.exe relatorio.py. Se o ambiente já existe, não precisa criá-lo novamente. Veja o guia de ambientes virtuais com venv para ativação e desativação.

E se aparecer No module named pip?

Nesse caso, o pip está ausente naquele interpretador. Em uma instalação que fornece ensurepip, você pode usar python -m ensurepip --upgrade. Algumas distribuições Linux separam esses componentes em pacotes do sistema; siga as instruções da distribuição para instalar suporte a venv e pip e então crie o ambiente do projeto.

Não tente contornar externally-managed-environment com sudo pip ou --break-system-packages só para seguir um tutorial. Esse aviso protege o Python gerenciado pelo sistema; um ambiente virtual normalmente é a solução adequada. Consulte a instalação de Python no Linux.

3. Nome de instalação e nome de importação podem ser diferentes

O pip instala distribuições; o código importa módulos e pacotes. Os nomes nem sempre coincidem:

Se um tutorial importa PIL, não conclua que precisa instalar uma distribuição chamada PIL. Confirme na documentação oficial. Isso também reduz o risco de baixar um pacote de nome semelhante que não tem relação com o projeto.

Não instale pacotes para módulos da biblioteca padrão, como json, csv ou pathlib. Se um módulo padrão novo estiver ausente, verifique a versão: tomllib só existe desde o Python 3.11.

Para um projeto recebido de uma empresa ou de um curso, prefira as dependências declaradas em requirements.txt ou pyproject.toml, conforme as instruções do repositório, em vez de instalar um pacote a cada erro.

4. Funciona no terminal, mas falha no VS Code ou PyCharm

VS Code

1. Abra a paleta com Ctrl + Shift + P ou Cmd + Shift + P.
2. Escolha Python: Select Interpreter.
3. Selecione o executável dentro de .venv.
4. Execute novamente pelo recurso da extensão Python e confira sys.executable.
5. Se necessário, abra um novo terminal para evitar manter um ambiente antigo ativado.

A extensão Code Runner pode usar um comando próprio, diferente do interpretador selecionado pela extensão Python. Configurações de depuração e testes também podem substituir o ambiente padrão. Por isso, vale mais conferir o executável no processo real do que confiar apenas no nome mostrado na barra de status.

Um sublinhado do Pylance como “Import could not be resolved” é um aviso de análise estática; ModuleNotFoundError é uma exceção durante a execução. Podem ter a mesma causa, mas não são a mesma coisa. Veja a configuração do VS Code para Python.

PyCharm

Confira o Python Interpreter nas configurações do projeto e a configuração de execução usada pelo botão Run. A localização exata dos menus varia entre versões. Selecione o Python do ambiente do projeto e repita o diagnóstico dentro do programa. O terminal embutido e a configuração de execução não necessariamente usam o mesmo ambiente.

O guia de PyCharm mostra a configuração do interpretador. Para notebooks, faça a verificação em uma célula: o guia de Conda e kernels no Jupyter trata desse fluxo específico.

5. Quando o módulo é seu: execute o pacote corretamente

Considere esta estrutura, com o terminal aberto na pasta projeto:

projeto/
└── automacao/
    ├── __init__.py
    ├── relatorio.py
    └── util.py

Conteúdo de automacao/util.py:

def saudacao():
    return "Relatório pronto"

Conteúdo de automacao/relatorio.py:

from automacao.util import saudacao

print(saudacao())

Execute a partir da raiz:

python -m automacao.relatorio

Ao executar python automacao/relatorio.py, a pasta do script entra no início do caminho de busca, não necessariamente a pasta que contém o pacote automacao. Isso pode impedir o import absoluto. Com -m, Python localiza o módulo pelo sistema de importação e o executa no contexto do pacote.

O arquivo __init__.py deixa explícito um pacote regular. Python também admite namespace packages sem esse arquivo; omiti-lo não é, por si só, prova de erro. Para começar, uma estrutura explícita costuma ser mais simples.

Projetos com pasta src

Em um projeto com layout src, a raiz normalmente não expõe diretamente o pacote:

projeto/
├── pyproject.toml
└── src/
    └── automacao/
        ├── __init__.py
        └── relatorio.py

Se o pyproject.toml estiver configurado para empacotar esse diretório, instale o projeto no ambiente:

python -m pip install -e .
python -m automacao.relatorio

-e significa instalação editável, útil para desenvolver sem reinstalar após cada alteração de código. O comando precisa de uma configuração de empacotamento válida; apenas criar um arquivo vazio chamado pyproject.toml não basta. Siga a configuração do repositório ou o tutorial oficial de empacotamento.

Evite espalhar sys.path.append(...) e caminhos absolutos da sua máquina pelo código. Esse atalho pode mascarar uma estrutura incorreta e falhar no computador de um colega, em testes ou no deploy.

6. Verifique arquivos com nomes de bibliotecas

Um arquivo local chamado requests.py, json.py ou pandas.py pode esconder a biblioteca real. O resultado frequentemente é AttributeError ou ImportError, mas também pode aparecer como erro de módulo ou submódulo ausente.

Se o import funciona, veja de onde ele veio:

import json

print(json.__file__)

Para json, o caminho normalmente deve apontar para a biblioteca padrão, não para um json.py criado na pasta do projeto. Renomeie arquivos conflitantes e reinicie o processo para descartar módulos que já ficaram em memória. Nem todo módulo possui __file__; esse diagnóstico é apropriado para módulos baseados em arquivos, como os exemplos acima.

Não apague ambientes ou reinstale bibliotecas antes de conferir essa hipótese simples.

Checklist para resolver sem tentativa e erro

• Li a última linha e o traceback completo para identificar o módulo ausente.
• Conferi sys.executable no processo que falha.
• Usei esse mesmo Python para executar -m pip --version e -m pip show.
• Confirmei o nome da distribuição na documentação, não só o nome do import.
• Selecionei o ambiente correto na IDE ou o kernel correto no notebook.
• Para código local, conferi a estrutura e executei a partir da raiz com -m quando apropriado.
• Verifiquei arquivos locais que escondem bibliotecas.
• Registrei as dependências conforme o padrão do projeto.

Para pedir ajuda em uma comunidade brasileira de Python, compartilhe o traceback, a estrutura de pastas, o comando usado e os caminhos dos interpretadores — removendo dados pessoais ou segredos. Isso permite reproduzir o problema, em vez de receber mais uma sugestão de “tente instalar de novo”.

Um projeto que documenta o ambiente e executa da mesma forma no terminal, na IDE e nos testes também é melhor como portfólio. Depois desse diagnóstico, avance para testes automatizados e explore as vagas Python.

Referências

• Exceções de Python: ModuleNotFoundError.
• Sistema de importação do Python.
• Documentação do pip: execução e instalação.
• Guia PyPA: distribuição versus pacote de importação.