---
title: "ModuleNotFoundError em Python: como corrigir"
url: "https://python.dev.br/blog/modulenotfounderror-python-pacote-instalado/"
markdown_url: "https://python.dev.br/blog/modulenotfounderror-python-pacote-instalado.MD"
description: "Corrija ModuleNotFoundError em Python: confira o interpretador, instale no ambiente certo e resolva imports no VS Code, PyCharm e projetos com pasta src local."
date: "2026-10-11"
author: "Equipe Python Dev BR"
---

# ModuleNotFoundError em Python: como corrigir

Corrija ModuleNotFoundError em Python: confira o interpretador, instale no ambiente certo e resolva imports no VS Code, PyCharm e projetos com pasta src local.


**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:

```text
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`.

| Situação | Primeira verificação | Correção provável |
|---|---|---|
| Biblioteca externa não instalada | `python -m pip show NOME_DA_DISTRIBUICAO` | Instalar a dependência no ambiente do projeto |
| Pip diz que já está instalada | `sys.executable` no processo que falha | Alinhar o interpretador da execução e da instalação |
| Funciona no terminal, não na IDE | Python selecionado no editor e no debugger | Selecionar o ambiente correto |
| O nome do import difere do pacote | Documentação oficial da biblioteca | Instalar a distribuição correta |
| Falha em módulo do próprio projeto | Estrutura de pastas e comando de execução | Usar `-m` ou instalar o projeto |
| Falha apenas no notebook | `sys.executable` em uma célula | Selecionar o kernel correto |

## 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:

```python
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:

```bash
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:

```bash
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:

```powershell
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:

```bash
.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](/guias/criando-virtual-environment/) 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](/guias/instalando-python-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:

| Instalação com pip | Import no código |
|---|---|
| `requests` | `import requests` |
| `beautifulsoup4` | `from bs4 import BeautifulSoup` |
| `Pillow` | `from PIL import Image` |
| `scikit-learn` | `import sklearn` |
| `python-docx` | `from docx import Document` |
| `PyYAML` | `import yaml` |

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`](/blog/tomllib-ler-toml-python/) 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](/guias/configurando-vscode-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](/guias/configurando-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](/blog/conda-jupyter-kernel-ambiente-python/) 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`:

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

Conteúdo de `automacao/util.py`:

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

Conteúdo de `automacao/relatorio.py`:

```python
from automacao.util import saudacao

print(saudacao())
```

Execute a partir da raiz:

```bash
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:

```text
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:

```bash
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](https://packaging.python.org/en/latest/tutorials/packaging-projects/).

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:

```python
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](/blog/pytest-parametrize-testes-parametrizados-python/) e explore as [vagas Python](/vagas/).

## Referências

- [Exceções de Python: ModuleNotFoundError](https://docs.python.org/3/library/exceptions.html#ModuleNotFoundError).
- [Sistema de importação do Python](https://docs.python.org/3/reference/import.html).
- [Documentação do pip: execução e instalação](https://pip.pypa.io/en/stable/user_guide/).
- [Guia PyPA: distribuição versus pacote de importação](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/).