Guia de Resolução de Problemas

January 30, 2026 · View on GitHub

Este guia fornece soluções para problemas comuns que pode encontrar ao trabalhar com o currículo de Data Science para Principiantes.

Índice

Problemas com Python e Jupyter

Python Não Encontrado ou Versão Errada

Problema: python: command not found ou versão errada do Python

Solução:

# Check Python version
python --version
python3 --version

# If Python 3 is installed as 'python3', create an alias
# On macOS/Linux, add to ~/.bashrc or ~/.zshrc:
alias python=python3
alias pip=pip3

# Or use python3 explicitly
python3 -m pip install jupyter

Solução para Windows:

  1. Reinstale o Python a partir de python.org
  2. Durante a instalação, selecione "Add Python to PATH"
  3. Reinicie o terminal/linha de comandos

Problemas na Ativação de Ambientes Virtuais

Problema: O ambiente virtual não ativa

Solução:

Windows:

# If you get execution policy error
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then activate
venv\Scripts\activate

macOS/Linux:

# Ensure the activate script is executable
chmod +x venv/bin/activate

# Then activate
source venv/bin/activate

Verificar ativação:

# Your prompt should show (venv)
# Check Python location
which python  # Should point to venv

Problemas com o Kernel do Jupyter

Problema: "Kernel não encontrado" ou "Kernel continua a falhar"

Solução:

# Reinstall kernel
python -m ipykernel install --user --name=datascience --display-name="Python (Data Science)"

# Or use the default kernel
python -m ipykernel install --user

# Restart Jupyter
jupyter notebook

Problema: Versão errada do Python no Jupyter

Solução:

# Install Jupyter in your virtual environment
source venv/bin/activate  # Activate first
pip install jupyter ipykernel

# Register the kernel
python -m ipykernel install --user --name=venv --display-name="Python (venv)"

# In Jupyter, select Kernel -> Change kernel -> Python (venv)

Problemas com Pacotes e Dependências

Erros de Importação

Problema: ModuleNotFoundError: No module named 'pandas' (ou outros pacotes)

Solução:

# Ensure virtual environment is activated
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Install missing package
pip install pandas

# Install all common packages
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

# Verify installation
python -c "import pandas; print(pandas.__version__)"

Falhas na Instalação com Pip

Problema: pip install falha com erros de permissão

Solução:

# Use --user flag
pip install --user package-name

# Or use virtual environment (recommended)
python -m venv venv
source venv/bin/activate
pip install package-name

Problema: pip install falha com erros de certificado SSL

Solução:

# Update pip first
python -m pip install --upgrade pip

# Try installing with trusted host (temporary workaround)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name

Conflitos de Versão de Pacotes

Problema: Versões incompatíveis de pacotes

Solução:

# Create fresh virtual environment
python -m venv venv-new
source venv-new/bin/activate  # or venv-new\Scripts\activate on Windows

# Install packages with specific versions if needed
pip install pandas==1.3.0
pip install numpy==1.21.0

# Or let pip resolve dependencies
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

Problemas com Jupyter Notebook

Jupyter Não Inicia

Problema: Comando jupyter notebook não encontrado

Solução:

# Install Jupyter
pip install jupyter

# Or use python -m
python -m jupyter notebook

# Add to PATH if needed (macOS/Linux)
export PATH="$HOME/.local/bin:$PATH"

Notebook Não Carrega ou Não Guarda

Problema: "Notebook falhou ao carregar" ou erros ao guardar

Solução:

  1. Verifique as permissões do ficheiro
# Make sure you have write permissions
ls -l notebook.ipynb
chmod 644 notebook.ipynb  # If needed
  1. Verifique se o ficheiro está corrompido
# Try opening in text editor to check JSON structure
# Copy content to new notebook if corrupted
  1. Limpe a cache do Jupyter
jupyter notebook --clear-cache

Célula Não Executa

Problema: Célula fica presa em "In [*]" ou demora muito tempo

Solução:

  1. Interrompa o kernel: Clique no botão "Interrupt" ou pressione I, I
  2. Reinicie o kernel: Menu Kernel → Restart
  3. Verifique loops infinitos no seu código
  4. Limpe a saída: Cell → All Output → Clear

Gráficos Não Aparecem

Problema: Gráficos matplotlib não aparecem no notebook

Solução:

# Add magic command at the top of notebook
%matplotlib inline

import matplotlib.pyplot as plt

# Create plot
plt.plot([1, 2, 3, 4])
plt.show()  # Make sure to call show()

Alternativa para gráficos interativos:

%matplotlib notebook
# Or
%matplotlib widget

Problemas com a Aplicação de Questionários

npm install Falha

Problema: Erros durante npm install

Solução:

# Clear npm cache
npm cache clean --force

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

# If still failing, try with legacy peer deps
npm install --legacy-peer-deps

Aplicação de Questionários Não Inicia

Problema: npm run serve falha

Solução:

# Check Node.js version
node --version  # Should be 12.x or higher

# Reinstall dependencies
cd quiz-app
rm -rf node_modules package-lock.json
npm install

# Try different port
npm run serve -- --port 8081

Porta Já Está em Uso

Problema: "Porta 8080 já está em uso"

Solução:

# Find and kill process on port 8080
# macOS/Linux:
lsof -ti:8080 | xargs kill -9

# Windows:
netstat -ano | findstr :8080
taskkill /PID <PID> /F

# Or use a different port
npm run serve -- --port 8081

Questionário Não Carrega ou Página em Branco

Problema: A aplicação de questionários carrega mas mostra uma página em branco

Solução:

  1. Verifique erros na consola do navegador (F12)
  2. Limpe a cache e os cookies do navegador
  3. Experimente outro navegador
  4. Certifique-se de que o JavaScript está ativado
  5. Verifique se bloqueadores de anúncios estão a interferir
# Rebuild the app
npm run build
npm run serve

Problemas com Git e GitHub

Git Não Reconhecido

Problema: git: command not found

Solução:

Windows:

  • Instale o Git a partir de git-scm.com
  • Reinicie o terminal após a instalação

macOS:

Nota: Se não tiver o Homebrew instalado, siga as instruções em https://brew.sh/ para instalá-lo primeiro.

# Install via Homebrew
brew install git

# Or install Xcode Command Line Tools
xcode-select --install

Linux:

sudo apt-get install git  # Debian/Ubuntu
sudo dnf install git      # Fedora

Falha ao Clonar

Problema: git clone falha com erros de autenticação

Solução:

# Use HTTPS URL
git clone https://github.com/microsoft/Data-Science-For-Beginners.git

# If you have 2FA enabled on GitHub, use Personal Access Token
# Create token at: https://github.com/settings/tokens
# Use token as password when prompted

Permissão Negada (publickey)

Problema: Autenticação com chave SSH falha

Solução:

# Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub
# Copy key: cat ~/.ssh/id_ed25519.pub
# Add at: https://github.com/settings/keys

Problemas com a Documentação Docsify

Comando Docsify Não Encontrado

Problema: docsify: command not found

Solução:

# Install globally
npm install -g docsify-cli

# If permission error on macOS/Linux
sudo npm install -g docsify-cli

# Verify installation
docsify --version

# If still not found, add npm global path
# Find npm global path
npm config get prefix

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:/usr/local/bin"

Documentação Não Carrega

Problema: Docsify serve mas o conteúdo não carrega

Solução:

# Ensure you're in the repository root
cd Data-Science-For-Beginners

# Check for index.html
ls index.html

# Serve with specific port
docsify serve --port 3000

# Check browser console for errors (F12)

Imagens Não Aparecem

Problema: Imagens mostram ícone de link quebrado

Solução:

  1. Verifique se os caminhos das imagens são relativos
  2. Certifique-se de que os ficheiros de imagem existem no repositório
  3. Limpe a cache do navegador
  4. Verifique se as extensões dos ficheiros correspondem (sensível a maiúsculas/minúsculas em alguns sistemas)

Problemas com Dados e Ficheiros

Erros de Ficheiro Não Encontrado

Problema: FileNotFoundError ao carregar dados

Solução:

import os

# Check current working directory
print(os.getcwd())

# Use absolute path
data_path = os.path.join(os.getcwd(), 'data', 'filename.csv')
df = pd.read_csv(data_path)

# Or use relative path from notebook location
df = pd.read_csv('../data/filename.csv')

# Verify file exists
print(os.path.exists('data/filename.csv'))

Erros ao Ler CSV

Problema: Erros ao ler ficheiros CSV

Solução:

import pandas as pd

# Try different encodings
df = pd.read_csv('file.csv', encoding='utf-8')
# or
df = pd.read_csv('file.csv', encoding='latin-1')
# or
df = pd.read_csv('file.csv', encoding='ISO-8859-1')

# Handle missing values
df = pd.read_csv('file.csv', na_values=['NA', 'N/A', ''])

# Specify delimiter if not comma
df = pd.read_csv('file.csv', delimiter=';')

Erros de Memória com Grandes Conjuntos de Dados

Problema: MemoryError ao carregar ficheiros grandes

Solução:

# Read in chunks
chunk_size = 10000
chunks = []
for chunk in pd.read_csv('large_file.csv', chunksize=chunk_size):
    # Process chunk
    chunks.append(chunk)
df = pd.concat(chunks)

# Or read specific columns only
df = pd.read_csv('file.csv', usecols=['col1', 'col2'])

# Use more efficient data types
df = pd.read_csv('file.csv', dtype={'column_name': 'int32'})

Problemas de Desempenho

Desempenho Lento do Notebook

Problema: Notebooks executam muito lentamente

Solução:

  1. Reinicie o kernel e limpe a saída

    • Kernel → Restart & Clear Output

  2. Feche notebooks não utilizados

  3. Otimize o código:

# Use vectorized operations instead of loops
# Bad:
result = []
for x in data:
    result.append(x * 2)

# Good:
result = data * 2  # NumPy/Pandas vectorization
  1. Amostre grandes conjuntos de dados:
# Work with sample during development
df_sample = df.sample(n=1000)  # or df.head(1000)

Problema: Navegador falha ou torna-se não responsivo

Solução:

  1. Feche separadores não utilizados
  2. Limpe a cache do navegador
  3. Aumente a memória do navegador (Chrome: chrome://settings/system)
  4. Use JupyterLab em vez disso:
pip install jupyterlab
jupyter lab

Obter Ajuda Adicional

Antes de Pedir Ajuda

  1. Consulte este guia de resolução de problemas
  2. Pesquise GitHub Issues
  3. Revise INSTALLATION.md e USAGE.md
  4. Experimente pesquisar a mensagem de erro online

Como Pedir Ajuda

Ao criar um problema ou pedir ajuda, inclua:

  1. Sistema Operativo: Windows, macOS ou Linux (qual distribuição)
  2. Versão do Python: Execute python --version
  3. Mensagem de Erro: Copie a mensagem de erro completa
  4. Passos para Reproduzir: O que fez antes de ocorrer o erro
  5. O que Já Tentou: Soluções que já tentou

Exemplo:

**Operating System:** macOS 12.0
**Python Version:** 3.9.7
**Error Message:** ModuleNotFoundError: No module named 'pandas'
**Steps to Reproduce:**
1. Activated virtual environment
2. Started Jupyter notebook
3. Tried to import pandas

**What I've Tried:**
- Ran pip install pandas
- Restarted Jupyter

Recursos da Comunidade

Documentação Relacionada

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original no seu idioma nativo deve ser considerado a fonte autoritária. Para informações críticas, recomenda-se uma tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas resultantes do uso desta tradução.