Conda no Jupyter: usar o ambiente certo e corrigir imports

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. Para aprender células, atalhos e gráficos, use o guia de Jupyter.

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

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:

conda --version
conda info --envs

Se está começando com uma instalação mínima, o Miniforge, mantido pelo conda-forge, 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:

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:

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:

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

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

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.

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:

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

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:

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:

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:

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

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:

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
• Documentação do IPython: instalação de kernels
• Documentação do Jupyter: kernels
• Miniforge: instaladores e instruções oficiais