---
title: "Conda no Jupyter: usar o ambiente certo e corrigir imports"
url: "https://python.dev.br/blog/conda-jupyter-kernel-ambiente-python/"
markdown_url: "https://python.dev.br/blog/conda-jupyter-kernel-ambiente-python.MD"
description: "Conecte um ambiente Conda ao Jupyter com ipykernel, confira sys.executable e corrija ModuleNotFoundError sem instalar pacotes no Python errado."
date: "2026-10-07"
author: "Equipe Python Dev BR"
---

# Conda no Jupyter: usar o ambiente certo e corrigir imports

Conecte um ambiente Conda ao Jupyter com ipykernel, confira sys.executable e corrija ModuleNotFoundError sem instalar pacotes no Python errado.


**Para usar um ambiente Conda no Jupyter, instale `ipykernel` nesse ambiente, registre o kernel e selecione-o no notebook.** Depois, execute `import sys; print(sys.executable)` em uma célula: o caminho deve corresponder ao Python do ambiente escolhido. Se o pacote aparece no terminal, mas o notebook mostra `ModuleNotFoundError`, conferir o interpretador é o primeiro passo — instalar novamente no `base` geralmente não resolve.

Vamos montar um ambiente local para analisar dados fictícios de pedidos de uma loja brasileira. O objetivo não é reinstalar o Anaconda, mas entender **qual Python executa cada comando**, conectar o notebook a ele e deixar o projeto fácil de recriar.

Para uma visão geral da distribuição e dos canais de pacotes, consulte o [glossário de Anaconda](/glossario/anaconda/). Para aprender células, atalhos e gráficos, use o [guia de Jupyter](/guias/configurando-jupyter-notebook/).

## Conda, JupyterLab e kernel: três peças diferentes

| Peça | Responsabilidade | Como conferir |
| --- | --- | --- |
| Conda | Criar ambientes e instalar pacotes, incluindo dependências nativas | `conda env list` e `conda list` |
| JupyterLab | Mostrar arquivos, células e resultados no navegador | Terminal usado para iniciar `jupyter lab` |
| Kernel Python | Executar o código das células e manter variáveis na memória | `sys.executable` dentro do notebook |
| Kernelspec | Registrar como iniciar um kernel e seu nome na interface | `jupyter kernelspec list` |

O servidor Jupyter pode rodar em um ambiente e iniciar um kernel de outro. Isso é válido, mas também explica por que instalar uma biblioteca no ambiente do servidor não garante que o notebook consiga importá-la.

Ativar `conda activate analise-br` muda o contexto do **terminal atual**. Não troca o Python de um notebook que já está aberto nem modifica o terminal de outra janela.

## 1. Preparar uma instalação Conda

Se você já usa Anaconda ou Miniconda, não precisa instalar outra distribuição para seguir o tutorial. No Windows, abra o prompt fornecido pela instalação. Em Linux e macOS, use um terminal inicializado para Conda.

Confira:

```bash
conda --version
conda info --envs
```

Se está começando com uma instalação mínima, o [Miniforge, mantido pelo conda-forge](https://github.com/conda-forge/miniforge), oferece instaladores por sistema e arquitetura. Baixe da página oficial, siga as instruções da plataforma e reabra o terminal após a inicialização. Não execute um instalador Linux no macOS nem misture arquivos para ARM e x86-64.

Os comandos abaixo usam explicitamente `conda-forge`, sem alterar a configuração global de canais. Em uma empresa, siga a política de repositórios aprovada pela equipe e confira os termos dos serviços usados; este tutorial não orienta a contornar restrições de acesso.

## 2. Criar um ambiente separado do base

Vamos usar Python 3.12 como versão concreta do exemplo, não como afirmação de que seja a versão mais recente. Instale as dependências juntas para o resolvedor considerar o conjunto:

```bash
conda create --name analise-br --override-channels -c conda-forge python=3.12 pandas jupyterlab ipykernel
conda activate analise-br
python -c "import sys; print(sys.executable)"
conda list
```

O caminho impresso deve apontar para o ambiente `analise-br`. A localização exata varia: no Windows costuma terminar em `envs\analise-br\python.exe`; em Linux e macOS, em `envs/analise-br/bin/python`.

Não faça o projeto no `base`: ele deve permanecer enxuto para administrar a instalação. Também não crie uma `.venv` dentro do ambiente Conda neste exercício. Sobrepor mecanismos de ambiente torna mais difícil saber de onde vêm os pacotes.

Crie uma pasta de trabalho vazia, como `pedidos-notebook`, e entre nela. Ela guardará o notebook e o arquivo de dependências, não a instalação do ambiente.

## 3. Registrar e selecionar o kernel

Com `analise-br` ainda ativo, execute:

```bash
python -m ipykernel install --user --name analise-br --display-name "Python (analise-br)"
jupyter kernelspec list
jupyter lab
```

- `python -m ipykernel` usa o Python ativo no terminal.
- `--name` define o identificador do registro.
- `--display-name` define o texto mostrado na interface.
- `--user` registra para o usuário atual, não para todos os usuários da máquina.

No JupyterLab, crie um notebook escolhendo **Python (analise-br)**. Se o notebook já existe, use o seletor de kernel ou a opção de trocar kernel no menu **Kernel**; o nome da opção depende da versão e do idioma da interface.

Na primeira célula, execute:

```python
import sys
import pandas as pd

print("Python:", sys.executable)
print("Versão:", sys.version)
print("Pandas:", pd.__version__)
print("Arquivo do Pandas:", pd.__file__)
```

Compare o executável com o caminho impresso no terminal. Essa verificação é mais confiável que o rótulo do kernel: o nome mostrado pode ter sido escolhido livremente ou pertencer a um registro antigo.

**Este fluxo é para Jupyter local.** Um notebook aberto no Google Colab executa em uma máquina remota; ativar Conda no seu computador não altera o Python do Colab. Veja o [comparativo entre Jupyter Notebook, JupyterLab e Colab](/comparacoes/jupyter-notebook-vs-jupyterlab-vs-google-colab/) para escolher onde trabalhar.

## 4. Executar uma análise pequena e verificável

Crie outra célula com dados fictícios. Valores em centavos evitam introduzir arredondamentos de ponto flutuante em uma simples soma de dinheiro:

```python
import pandas as pd

pedidos = pd.DataFrame([
    {"cidade": "Recife", "valor_centavos": 12990, "status": "pago"},
    {"cidade": "Recife", "valor_centavos": 5000, "status": "cancelado"},
    {"cidade": "Curitiba", "valor_centavos": 8900, "status": "pago"},
    {"cidade": "Recife", "valor_centavos": 7010, "status": "pago"},
])

pagos = pedidos.loc[pedidos["status"].eq("pago")]
resumo = (
    pagos.groupby("cidade", as_index=False)["valor_centavos"]
    .sum()
    .sort_values("cidade")
    .reset_index(drop=True)
)

assert resumo["valor_centavos"].sum() == 28900
resumo
```

O resultado esperado é:

| cidade | valor_centavos |
| --- | ---: |
| Curitiba | 8900 |
| Recife | 20000 |

O `assert` é uma conferência simples, não uma suíte completa de testes. Ele ajuda a detectar edição acidental nos dados ou na regra de filtragem. Para manipulações mais amplas, continue com a [introdução ao Pandas](/blog/introducao-ao-pandas/).

Antes de salvar, reinicie o kernel e execute todas as células em ordem. Um notebook que só funciona graças a variáveis criadas numa sessão anterior não está pronto para compartilhar.

## 5. Resolver ModuleNotFoundError sem instalar às cegas

Primeiro, descubra **onde** houve o erro e **onde** você instalou o pacote:

| Sintoma | Verificação | Ação |
| --- | --- | --- |
| Import funciona no terminal, mas falha na célula | Compare `sys.executable` nos dois lugares | Selecione o kernel correto |
| Ambiente não aparece no seletor | Confira `jupyter kernelspec list` | Registre `ipykernel` usando o Python desse ambiente |
| Kernel selecionado não inicia | Confira o caminho em `kernel.json` do registro | Recrie o ambiente ou registre novamente com um Python existente |
| Import continua falhando no ambiente correto | Rode `conda list` e confira o nome do pacote | Instale a dependência que realmente falta |
| Import aponta para um arquivo do projeto | Confira `pacote.__file__`, quando o import funcionar | Renomeie arquivos como `pandas.py` e reinicie o kernel |

Por exemplo, se o kernel correto não tem Matplotlib, instale pelo terminal:

```bash
conda activate analise-br
conda install --override-channels -c conda-forge matplotlib
```

Reinicie o kernel depois de instalar ou atualizar dependências. Bibliotecas já importadas podem continuar carregadas na memória; instalar uma versão diferente no disco não substitui automaticamente esses objetos.

### E se o pacote só estiver no PyPI?

Instale primeiro as dependências disponíveis via Conda. Se precisar de pip, adicione-o explicitamente ao ambiente:

```bash
conda activate analise-br
conda install --override-channels -c conda-forge pip
python -m pip --version
```

Depois use `python -m pip install nome-do-pacote`, substituindo o nome pela dependência real. Evite `!pip install` como solução automática: um comando de shell no notebook pode encontrar outro executável pelo `PATH`. O IPython também oferece `%pip`, pensado para o kernel atual, mas em um projeto Conda é preferível manter as instalações documentadas no ambiente.

Se houver mudanças significativas após instalações via pip, recrie o ambiente a partir de uma especificação revisada em vez de alternar gerenciadores indefinidamente. Não use `sudo pip` nem instale no Python global para corrigir esse notebook.

## 6. Compartilhar o ambiente sem copiar a instalação

Salve um arquivo `environment.yml` na pasta do projeto:

```yaml
name: analise-br
channels:
  - conda-forge
  - nodefaults
dependencies:
  - python=3.12
  - pandas
  - jupyterlab
  - ipykernel
```

`nodefaults` evita acrescentar os canais padrão ao criar esse ambiente a partir do arquivo. Para recriar em outra máquina:

```bash
conda env create --file environment.yml
conda activate analise-br
python -m ipykernel install --user --name analise-br --display-name "Python (analise-br)"
jupyter lab
```

A outra máquina deve estar sem um ambiente com esse nome; caso já exista, escolha um nome novo ou avalie a atualização antes de executar comandos. O registro do kernel é local: versionar o YAML não o instala automaticamente.

Esse arquivo declara **dependências de alto nível**, não versões exatas de todos os pacotes transitivos. Uma recriação futura pode resolver versões diferentes. Para auditoria e reprodução mais rigorosa, registre as versões testadas e avalie uma ferramenta de lock compatível com as plataformas da equipe.

Uma opção para recuperar a intenção de um ambiente já criado é:

```bash
conda env export --from-history > environment-history.yml
```

Revise o resultado: ele prioriza solicitações feitas ao Conda e não é uma lista completa de tudo que pip pode ter instalado. Remova caminhos locais, se presentes, antes de compartilhar. Versione o notebook e a especificação; não copie pastas `envs`, caches ou arquivos pessoais para o Git.

## 7. Limpar registros antigos com cuidado

Quando um ambiente é removido ou movido, seu kernelspec pode continuar aparecendo no Jupyter. Liste os registros e remova apenas o que ficou obsoleto:

```bash
jupyter kernelspec list
jupyter kernelspec uninstall analise-br
```

O segundo comando remove **o registro do kernel**, não o ambiente nem os arquivos `.ipynb`. Só execute se quer mesmo retirar essa opção da interface. Para voltar a usá-la, ative o ambiente e repita o comando de registro com `ipykernel`.

Não remova um ambiente que ainda executa um notebook. Encerre o kernel e confirme quais projetos dependem dele antes de qualquer limpeza.

## Checklist antes de entregar o notebook

- O kernel usa o mesmo `sys.executable` verificado no terminal.
- As dependências estão num ambiente de projeto, não no `base`.
- O notebook executa do início ao fim após reiniciar o kernel.
- A especificação de ambiente está versionada e foi revisada.
- Os dados do exemplo são fictícios; não há credenciais ou dados pessoais nas saídas.
- O README do projeto explica como recriar o ambiente e registrar o kernel.

O ponto central é separar **interface, ambiente e processo Python**. Com essa separação, um erro de import deixa de ser motivo para reinstalar o Anaconda inteiro e vira um diagnóstico verificável.

## Referências

- [Documentação do Conda: gerenciamento de ambientes](https://docs.conda.io/projects/conda/en/stable/user-guide/tasks/manage-environments.html)
- [Documentação do IPython: instalação de kernels](https://ipython.readthedocs.io/en/stable/install/kernel_install.html)
- [Documentação do Jupyter: kernels](https://docs.jupyter.org/en/latest/projects/kernels.html)
- [Miniforge: instaladores e instruções oficiais](https://github.com/conda-forge/miniforge)