Antes de qualquer linha de código, você vai instalar cinco ferramentas: Python, Git, um editor, o Ollama e um modelo. No fim, um script confirma que está tudo certo. Reserve de 30 a 60 minutos, a maior parte esperando downloads.

Roteiro de instalação: três sistemas, um ambiente.

Siga só a linha do seu sistema. No Windows, o WSL2 transforma a instalação numa instalação de Linux.

0.1 O que vamos instalar

Ferramenta	Para que serve	Licença
Python	A linguagem dos exemplos	PSF (livre)
Git	Guardar o histórico do código e baixar projetos	GPL 2.0
VSCodium	Editor de código. É o VS Code compilado sem a telemetria da Microsoft	MIT
Ollama	Baixa e roda os modelos de linguagem	MIT
Gemma 4 E4B	O primeiro modelo, pequeno e com suporte a ferramentas	Apache 2.0

Uma observação honesta: o sistema operacional fica a seu critério, e o Windows e o macOS não são livres. Também não são livres o driver da NVIDIA e as ferramentas de linha de comando da Apple, que o Homebrew exige. Tudo o que a apostila instala por cima é livre.

0.2 Antes de começar

Tenho senha de administrador da máquina
Tenho pelo menos 10 GB livres no disco
Estou numa internet que aguenta baixar uns 5 GB
Sei qual é meu sistema: GNU/Linux, Windows ou macOS

Agora vá direto para a seção do seu sistema (0.3, 0.4 ou 0.5). Depois, todo mundo se encontra na seção 0.6.

0.3 GNU/Linux

Os comandos abaixo valem para Ubuntu, Debian e derivados (Linux Mint, Pop!_OS) e para Fedora. Onde forem diferentes, aparecem lado a lado.

Passo 1 — Abrir o terminal. Aperte Ctrl + Alt + T ou procure “Terminal” no menu de aplicativos.

Passo 2 — Atualizar o sistema. Sempre comece assim. Evita conflito de pacotes velhos.

# Ubuntu / Debian
sudo apt update && sudo apt upgrade -y

# Fedora
sudo dnf upgrade --refresh -y

O sudo pede sua senha. Enquanto você digita, nada aparece na tela. É normal: digite e aperte Enter.

Passo 3 — Instalar Python, Git e curl.

# Ubuntu / Debian
sudo apt install -y python3 python3-venv python3-pip git curl

# Fedora (o Python já vem com o venv)
sudo dnf install -y python3 python3-pip git curl

Confira as versões:

python3 --version   # precisa ser 3.11 ou mais novo
git --version

O Python 3.10 chegou ao fim do suporte em outubro de 2026. Se sua distribuição ainda traz o 3.10, atualize a distribuição para uma versão mais recente.

Passo 4 — Instalar o VSCodium. Os comandos vêm do site oficial do VSCodium. Eles adicionam o repositório do projeto, para o editor se atualizar junto com o sistema.

Ubuntu 24.04 ou mais novo, ou Debian 13:

wget -qO - https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/raw/master/pub.gpg \
  | gpg --dearmor \
  | sudo dd of=/usr/share/keyrings/vscodium-archive-keyring.gpg

echo -e 'Types: deb\nURIs: https://download.vscodium.com/debs\nSuites: vscodium\nComponents: main\nArchitectures: amd64 arm64\nSigned-by: /usr/share/keyrings/vscodium-archive-keyring.gpg' \
  | sudo tee /etc/apt/sources.list.d/vscodium.sources

sudo apt update && sudo apt install -y codium

Fedora:

sudo tee -a /etc/yum.repos.d/vscodium.repo << 'EOF'
[gitlab.com_paulcarroty_vscodium_repo]
name=gitlab.com_paulcarroty_vscodium_repo
baseurl=https://paulcarroty.gitlab.io/vscodium-deb-rpm-repo/rpms/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://gitlab.com/paulcarroty/vscodium-deb-rpm-repo/raw/master/pub.gpg
metadata_expire=1h
EOF

sudo dnf install -y codium

Para abrir: digite codium no terminal ou procure “VSCodium” no menu.

Passo 5 — Instalar o Ollama. Um comando só, da documentação oficial:

curl -fsSL https://ollama.com/install.sh | sh

O script instala o programa, cria um serviço que liga junto com o computador e detecta placas NVIDIA e AMD sozinho. Confira:

ollama --version
systemctl status ollama   # deve mostrar "active (running)". Aperte q para sair

Passo 6 — Placa de vídeo (só se você tiver uma). Sem placa dedicada, pule este passo. O Ollama roda na CPU.

Placa	O que fazer
NVIDIA, no Ubuntu	`sudo ubuntu-drivers install` e reinicie. Depois, `nvidia-smi` deve listar sua placa
NVIDIA, no Fedora	Ative o repositório RPM Fusion, rode `sudo dnf install -y akmod-nvidia xorg-x11-drv-nvidia-cuda`, espere uns 5 minutos para o módulo compilar e reinicie
AMD Radeon	O Ollama exige o ROCm 7 da AMD. Siga o guia do Ollama para GPUs e confira se sua placa está na lista
Intel ou AMD sem ROCm	O Ollama pode usar Vulkan, com os drivers livres do Mesa. Veja o mesmo guia

O Ollama exige driver NVIDIA 550 ou mais novo. Placas mais antigas (capacidade de computação 5.0 a 6.2) precisam do driver 570 ou mais novo.

Agora pule para a seção 0.6.

0.4 Windows (com WSL2)

No Windows, você vai rodar um Ubuntu de verdade dentro do sistema, usando o WSL2 (Subsistema do Windows para Linux). Parece volta, mas economiza tempo: todos os comandos da apostila passam a ser iguais aos do Linux.

Passo 1 — Conferir a versão do Windows. Aperte Win + R, digite winver e Enter. Precisa ser Windows 11, ou Windows 10 versão 2004 (build 19041) ou mais nova.

Passo 2 — Instalar o WSL2 com Ubuntu. Clique com o botão direito no menu Iniciar e escolha Terminal (Administrador) ou Windows PowerShell (Administrador). Digite:

wsl --install

Esse comando ativa o WSL2, baixa o kernel Linux e instala o Ubuntu. Reinicie o computador quando terminar.

Passo 3 — Criar seu usuário Linux. Depois de reiniciar, o Ubuntu abre sozinho (ou procure “Ubuntu” no menu Iniciar). Ele pede:

um nome de usuário, só com letras minúsculas e sem espaço;
uma senha, que será usada no sudo. Ela não aparece enquanto você digita.

Passo 4 — Confirmar que é o WSL versão 2. No PowerShell:

wsl --list --verbose

A coluna VERSION precisa mostrar 2. Se mostrar 1, rode wsl --set-version Ubuntu 2.

Passo 5 — Instalar tudo dentro do Ubuntu. Abra o Ubuntu e siga os Passos 2, 3 e 5 da seção 0.3, na versão Ubuntu. O instalador do Ollama funciona igual.

Passo 6 — Placa de vídeo NVIDIA. Aqui está a pegadinha mais comum:

Instale ou atualize o driver NVIDIA só no Windows, pelo site da NVIDIA.
Nunca instale driver NVIDIA dentro do Ubuntu do WSL. O Windows já entrega a placa para o Linux, e um driver instalado dentro quebra essa ponte.
Para testar, rode nvidia-smi dentro do Ubuntu. Se a placa aparecer, está pronto.

Passo 7 — Instalar o VSCodium. O caminho mais simples é instalar o VSCodium dentro do Ubuntu, com o Passo 4 da seção 0.3. O Windows 11 abre programas gráficos do Linux numa janela normal. Para abrir uma pasta, rode codium . no terminal do Ubuntu.

Onde guardar seus projetos. Crie os projetos dentro da pasta do Linux (~, ou seja, /home/seu-usuario). Evite /mnt/c/..., que é o disco do Windows visto pelo Linux: é bem mais lento. Para ver seus arquivos Linux pelo Explorador do Windows, digite explorer.exe . no Ubuntu.

Agora pule para a seção 0.6.

0.5 macOS

No Mac, o Homebrew faz o papel do gerenciador de pacotes do Linux. Ele é livre (licença BSD) e instala todo o resto com um comando cada.

Passo 1 — Abrir o Terminal. Aperte Cmd + Espaço, digite “Terminal” e Enter.

Passo 2 — Instalar as ferramentas de linha de comando da Apple. O Homebrew precisa delas.

xcode-select --install

Uma janela pede confirmação. Clique em Instalar e espere terminar.

Passo 3 — Instalar o Homebrew. Comando do site oficial:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

No fim, o instalador mostra uma seção “Next steps” com dois ou três comandos. Copie e rode esses comandos: eles colocam o brew no seu PATH. Depois, feche e abra o Terminal e confira com brew --version.

Passo 4 — Instalar Python e Git.

brew install python git
python3 --version
git --version

Passo 5 — Instalar o VSCodium.

brew install --cask vscodium

Na primeira vez, o macOS pode pedir confirmação para abrir um app baixado da internet. Para abrir uma pasta pelo terminal, rode codium ..

Passo 6 — Instalar e ligar o Ollama.

brew install ollama
brew services start ollama   # liga agora e a cada login
ollama --version

Chip Apple ou Intel? Clique no menu Apple e em Sobre este Mac.

Chip Apple (M1 em diante): o Ollama usa a GPU do chip automaticamente. A memória é compartilhada, então um Mac com 16 GB roda modelos de até uns 8B com folga.
Intel: funciona, mas só pela CPU. Fique nos modelos pequenos, de 1B a 4B.

0.6 Passos comuns aos três sistemas

A partir daqui, os comandos são iguais para todo mundo: no Linux, no Ubuntu do WSL e no Terminal do Mac.

Passo 1 — Apresentar-se ao Git. Ele grava seu nome em cada alteração.

git config --global user.name "Seu Nome"
git config --global user.email "voce@exemplo.com"
git config --global init.defaultBranch main

Passo 2 — Criar a pasta da apostila e o ambiente virtual.

mkdir -p ~/agentes && cd ~/agentes
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install requests ollama
git init

O (.venv) aparece no começo da linha: o ambiente está ativo. Toda vez que abrir um terminal novo, entre na pasta e rode source .venv/bin/activate de novo.

Passo 3 — Baixar o primeiro modelo. São alguns GB, então pode demorar.

ollama pull gemma4:e4b
ollama run gemma4:e4b "Responda em uma frase: o que é um agente de IA?"

Se a máquina tiver só 8 GB de RAM, use gemma4:e2b, que é menor.

Passo 4 — Preparar o VSCodium. Abra a pasta com codium ~/agentes. Na barra lateral, clique em Extensões (Ctrl + Shift + X, ou Cmd + Shift + X no Mac) e instale:

Python, para destacar o código e rodar arquivos;
Ruff, para apontar erros e formatar o código.

As extensões vêm do Open VSX, a loja aberta usada pelo VSCodium. Depois, aperte Ctrl + Shift + P, digite “Python: Select Interpreter” e escolha o que tem .venv no caminho.

0.7 Conferindo tudo com um script

Salve o arquivo abaixo como verificar_ambiente.py dentro de ~/agentes. São 11 linhas que conferem o que este capítulo instalou.

import shutil, sys, urllib.request

print("Python 3.11+:", "OK" if sys.version_info >= (3, 11) else "FALTA")
print("venv ativo:  ", "OK" if sys.prefix != sys.base_prefix else "FALTA")
print("Git:         ", "OK" if shutil.which("git") else "FALTA")
print("Ollama:      ", "OK" if shutil.which("ollama") else "FALTA")
try:
    urllib.request.urlopen("http://localhost:11434", timeout=3)
    print("Servidor:    ", "OK")
except Exception:
    print("Servidor:     FALTA (rode: ollama serve)")

Cada linha testa uma coisa e imprime OK ou FALTA. A última tenta “bater na porta” do Ollama: se ele responder, o servidor está ligado.

Rode com o ambiente virtual ativo:

python verificar_ambiente.py

Saída esperada numa máquina pronta:

Python 3.11+: OK
venv ativo:   OK
Git:          OK
Ollama:       OK
Servidor:     OK

Apareceu FALTA? Volte ao passo correspondente ou veja a tabela da seção 0.8. Para conferir os modelos baixados, rode ollama list.

0.8 Deu erro? Os problemas mais comuns

Sintoma	Causa provável	Solução
`python3: command not found`	Python não instalado ou fora do PATH	Refaça o Passo 3 (Linux) ou o Passo 4 (Mac)
`error: externally-managed-environment` ao usar pip	Você está instalando fora do venv	Ative o venv com `source .venv/bin/activate` e tente de novo
`brew: command not found` no Mac	Os “Next steps” do Homebrew não foram rodados	Rode os comandos que o instalador mostrou e reabra o Terminal
`Servidor: FALTA`	O serviço não está ligado	Linux: `sudo systemctl start ollama`. Mac: `brew services start ollama`. Ou rode `ollama serve` num terminal separado
Modelo muito lento	Rodando na CPU ou grande demais para a memória	Rode `ollama ps`: a coluna PROCESSOR mostra quanto está na GPU. Troque por um modelo menor
`nvidia-smi` falha no WSL	Driver desatualizado no Windows	Atualize o driver no Windows, rode `wsl --update` e `wsl --shutdown` no PowerShell e abra o Ubuntu de novo
GPU sumiu depois de suspender o Linux	Falha conhecida do driver NVIDIA	`sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm`
`codium` não abre janela no WSL	Windows 10 antigo, sem suporte a apps gráficos	Atualize o WSL com `wsl --update` no PowerShell. Se não resolver, instale o VSCodium no Windows com `winget install vscodium`