Ollama: o guia completo para iniciantes em LLM local [2026]

Ollama é uma ferramenta gratuita e de código aberto para rodar LLMs abertos (grandes modelos de linguagem) no seu próprio computador. Ela funciona no Windows, no macOS e no Linux, e uma única linha, ollama run nome-do-modelo, leva você do download do modelo até a conversa com ele. Enquanto está rodando, ela sobe um servidor de API em localhost:11434, então seus próprios apps e ferramentas como o Claude Code também podem chamá-la. Além dos modelos que rodam na sua máquina, agora ela também roda modelos na nuvem, cujo nome termina em :cloud, com os mesmos comandos.

Este guia se concentra em como usar o Ollama em si, conferido com o texto original do repositório oficial no GitHub (incluindo o código-fonte), da documentação oficial e da página de preços (em 12 de novembro de 2026). Para LLMs locais em geral, veja como começar com um LLM local; para escolher o modelo, nossa comparação dos melhores modelos de LLM local; para calcular a VRAM necessária, o artigo sobre requisitos de hardware; e para conectar um modelo ao seu editor, o artigo sobre Ollama + Cline.

1. O que é o Ollama? Duas formas de rodar modelos: local e na nuvem

O Ollama é uma ferramenta gratuita e de código aberto para rodar modelos abertos (Gemma, Qwen, gpt-oss e outros) com facilidade no seu próprio PC. Ele cuida da parte chata em segundo plano (baixar modelos, lidar com formatos de quantização, configurar o uso da GPU), e você só precisa "dizer o nome do modelo e rodar". A inferência se apoia no llama.cpp, e nos Macs com Apple Silicon alguns modelos também têm versões que rodam no MLX da Apple.

Há duas formas de rodar um modelo, e a escolha muda completamente o PC de que você precisa e quanto você paga.

Uma ferramenta parecida é o LM Studio. Grosso modo: Ollama = centrado em comandos e API, voltado a desenvolvedores, automação e conexão com agentes; LM Studio = centrado em interface gráfica, para quem quer ir da busca do modelo à conversa sem sair da janela. Os dois são gratuitos. As diferenças entre local e nuvem em si (custo, desempenho, privacidade) estão na nossa comparação entre LLMs locais e na nuvem.

2. Como instalar o Ollama (Windows / macOS / Linux / Docker)

A página de download oficial e o README no GitHub trazem dois caminhos para cada sistema: um comando de uma linha para colar no terminal ou um instalador manual. Os dois dão o mesmo resultado.

Windows

Se preferir não usar comandos, baixe o OllamaSetup.exe na página de download e execute. Segundo a página oficial do Windows, ele é instalado por padrão na sua pasta de usuário, e os modelos podem ocupar ainda de dezenas a centenas de GB. Se o drive C: estiver apertado, mude o local de instalação com OllamaSetup.exe /DIR="d:\some\location" e o dos modelos com a variável de ambiente OLLAMA_MODELS (seção 9). Depois de instalado, o Ollama fica em segundo plano e o comando ollama funciona tanto no cmd quanto no PowerShell.

macOS

Na instalação manual, abra o Ollama.dmg e arraste o app para a pasta Aplicativos. Na primeira abertura, se o comando ollama não estiver no PATH, o app pede permissão para criar um link em /usr/local/bin (página oficial do macOS).

Linux

A instalação manual sem o script e o pacote adicional para GPUs AMD estão na página oficial do Linux. No Linux não há um app como no Windows e no macOS: o uso é por comandos e pela API.

Docker

A imagem oficial ollama/ollama está no Docker Hub. Um início mínimo só com CPU fica assim. Para GPUs NVIDIA, instale o NVIDIA Container Toolkit e acrescente --gpus=all; para GPUs AMD, use a imagem ollama/ollama:rocm (página oficial do Docker). O Docker Desktop no macOS não consegue usar a GPU (FAQ oficial), então no Mac é mais rápido instalar o app diretamente.

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
docker exec -it ollama ollama run gemma4:e2b

3. Vai rodar rápido na sua GPU? (GPUs compatíveis de relance)

Se o Ollama não consegue usar sua GPU, ele passa para a CPU: nenhum erro aparece, mas fica várias vezes mais lento. Antes de instalar, veja se a sua GPU está na página oficial Hardware support. Os pontos principais estão abaixo.

Para saber se um modelo foi mesmo carregado na GPU, rode ollama ps enquanto ele está em uso. Se a coluna PROCESSOR mostrar 100% GPU, ele está todo na GPU; uma divisão como 48%/52% CPU/GPU significa que não coube na VRAM (FAQ oficial). O que reduzir quando há divisão está na tabela da seção 9. As estimativas de VRAM por GPU estão no nosso artigo sobre requisitos de hardware.

4. Lista de comandos do Ollama

A tabela reúne os comandos da referência oficial da CLI e os definidos no código-fonte (cmd/cmd.go). No dia a dia, você vai usar sobretudo os seis primeiros.

O ollama run tem opções úteis. Com --verbose, ele mostra o tempo gasto e os tokens por segundo (eval rate) depois de cada resposta, então dá para comparar a velocidade em números ao trocar de modelo ou de tag. --think=false faz os modelos que mostram o raciocínio pararem de mostrá-lo, --format json devolve a resposta em JSON e --keepalive 30m muda quanto tempo o modelo fica na memória. Com modelos que leem imagens, basta incluir o caminho do arquivo no texto, como em ollama run gemma4 "O que tem nesta imagem? ./photo.png".

Durante a conversa (depois do prompt >>>) há comandos próprios que começam com /. /bye sai, /? lista todos, /clear apaga o contexto da conversa e /set parameter num_ctx 8192 muda o tamanho de contexto na hora. Para digitar várias linhas de uma vez, coloque-as entre """.

5. Como baixar modelos e ler as tags

Um modelo é indicado por nome + tag. Sem tag, usa-se latest, mas o tamanho para o qual latest aponta varia de modelo para modelo. Instalando sem olhar, pode vir uma versão bem maior do que você esperava. Usando como exemplo a lista oficial de tags do gemma4, a tabela mostra como lê-las (conforme exibido em 12 de novembro de 2026).

Os tamanhos aparecem como faixas porque uma tag contém vários formatos, e o que combina com a sua máquina é escolhido. No latest do gemma4, o mínimo de 6,6 GB corresponde a e4b-it-q4_K_M e o máximo de 9,5 GB a e4b-mlx. Na dúvida, escolha uma tag sem sufixo (como gemma4:e4b) e o Ollama escolhe o formato certo para a sua máquina. Os formatos de quantização em si (como ler o Q4_K_M do GGUF etc.) estão no nosso artigo sobre formatos de quantização.

Os valores de VRAM são uma referência: o tamanho do modelo mais uma folga para a conversa (o contexto). O guia de início rápido oficial também recomenda "8 GB de VRAM (ou memória unificada no Mac)" para o gemma4:e2b (cerca de 7,2 GB no formato instalado por padrão). Depois de instalar, ollama show gemma4 mostra o número de parâmetros, a quantização e o tamanho de contexto.

6. Usando com interface gráfica (o app do Ollama, Open WebUI e mais)

Se você prefere evitar o terminal, comece abrindo o app do próprio Ollama. As versões para Windows e macOS trazem uma janela para escolher um modelo e conversar (post oficial do blog "Ollama's new app"). O Linux não tem app, então use uma das outras interfaces abaixo.

7. Modelos na nuvem e preços

Quando a sua GPU não dá conta de um modelo grande, você pode usar modelos na nuvem que rodam nos servidores do Ollama, com o mesmo fluxo de trabalho. Entre no ollama.com com ollama signin e informe um nome terminado em :cloud, como ollama run gemma4:cloud. Não é preciso baixar nada (página oficial de Cloud). Os planos são estes (página de preços, em 12 de novembro de 2026).

O uso é contado pelo preço de cada modelo por milhão de tokens. A versão na nuvem do gemma4, por exemplo, custa $0,14 na entrada e $0,40 na saída. Com 1 milhão de tokens de entrada e 200 mil de saída, dá 0,14 + 0,40 × 0,2 = cerca de $0,22. Nessa proporção, os $60 mensais do Pro dão para umas 270 rodadas assim (60 ÷ 0,22). O uso incluído não passa para o mês seguinte. Os modelos que rodam na sua máquina são ilimitados e gratuitos em todos os planos.

8. Usando a API (compatível com OpenAI e com Anthropic)

A grande força do Ollama é a API local. Por padrão, o servidor escuta em 127.0.0.1:11434; mande requisições para lá e seus apps, scripts e ferramentas podem usar um LLM local. Há três formatos de requisição.

/api/chat (enviar o histórico da conversa)

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'

A resposta vem em message.content. Se você tirar "stream": false, a resposta chega aos poucos em linhas de JSON (streaming é o padrão). Para uma única resposta, também dá para mandar um "prompt" para /api/generate. O exemplo acima é para os shells do macOS e do Linux; o PowerShell do Windows trata aspas de outro jeito, então use esta forma da página oficial do Windows (só o nome do modelo foi trocado).

(Invoke-WebRequest -method POST -Body '{"model":"gemma4", "prompt":"Why is the sky blue?", "stream": false}' -uri http://localhost:11434/api/generate ).Content | ConvertFrom-json

Compatível com OpenAI (/v1)

Com a biblioteca oficial da OpenAI, basta apontar base_url para o Ollama. Segundo a documentação oficial, num servidor local a chave de API é "obrigatória, mas ignorada", então qualquer texto serve.

from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1/',
    api_key='ollama',  # required but ignored
)

chat_completion = client.chat.completions.create(
    messages=[{'role': 'user', 'content': 'Say this is a test'}],
    model='gemma4',
)
print(chat_completion.choices[0].message.content)

Compatível com Anthropic (conectar o Claude Code)

A página oficial de compatibilidade com a Anthropic manda definir estas duas variáveis de ambiente nas ferramentas feitas para a API da Anthropic. Mesmo sem defini-las você mesmo, o ollama launch claude abre o Claude Code já conectado.

export ANTHROPIC_AUTH_TOKEN=ollama  # required but ignored
export ANTHROPIC_BASE_URL=http://localhost:11434

As duas camadas de compatibilidade cobrem só parte das APIs originais. O formato Responses, por exemplo, não guarda estado, então é preciso mandar o histórico da conversa toda vez. Ao usar um modelo local com um agente de programação, o tamanho de contexto da próxima seção é o ponto-chave.

9. Personalização (Modelfile, variáveis de ambiente, ajuste de memória)

Modelfile: crie seu próprio modelo

Um Modelfile é um arquivo de configuração bem parecido com um Dockerfile. Você parte de um modelo base (FROM, obrigatório), acrescenta parâmetros (PARAMETER) e um prompt de sistema (SYSTEM) e ganha "seu próprio modelo", que sempre se comporta do mesmo jeito. Um exemplo mínimo:

FROM gemma4
PARAMETER temperature 0.7
PARAMETER num_ctx 16384
SYSTEM """Você é um assistente objetivo. Comece pelo mais importante e responda em português."""

Salve isso num arquivo chamado Modelfile e rode o seguinte na mesma pasta. Com num_ctx no Modelfile, você aumenta o tamanho de contexto só deste modelo, sem mexer no padrão do servidor inteiro.

ollama create my-assistant -f Modelfile
ollama run my-assistant

ollama show --modelfile gemma4 mostra o Modelfile de um modelo existente. Copiar e editar é o caminho mais rápido.

Principais variáveis de ambiente

O comportamento do servidor é controlado por variáveis de ambiente. ollama serve --help mostra a lista completa. Estas são as mais usadas, com os valores padrão escritos no código-fonte (envconfig/config.go) e na FAQ oficial.

O jeito de definir varia conforme o sistema (FAQ oficial). No Windows, feche o Ollama pela barra de tarefas, adicione uma variável de usuário nas configurações de variáveis de ambiente e abra o Ollama de novo pelo menu Iniciar. No macOS, defina com algo como launchctl setenv OLLAMA_HOST "0.0.0.0:11434" e reinicie o app. No Linux (rodando com systemd), faça assim:

systemctl edit ollama.service
# em [Service], acrescente uma linha por variável
# Environment="OLLAMA_HOST=0.0.0.0:11434"
systemctl daemon-reload
systemctl restart ollama

Ajustes para pouca memória ou contexto longo

Com menos de 24 GiB de VRAM, o tamanho de contexto padrão é de só 4k (cerca de 4.000 tokens). A página oficial Context length recomenda pelo menos 64.000 tokens para busca na web, agentes e ferramentas de programação. Se faltar, o modelo esquece o que veio antes sem mostrar erro, por isso a tabela traz o ajuste para cada objetivo, para você partir do sintoma.

Depois de mudar algo, confira com ollama ps se a coluna CONTEXT mostra o tamanho desejado e se PROCESSOR continua em 100% GPU. Como o tamanho de contexto vira memória está calculado no nosso artigo sobre requisitos de hardware, e os sintomas de um agente que fica sem contexto, no artigo sobre Ollama + Cline.

10. Solução de problemas

Os tropeços mais comuns e as soluções da FAQ oficial e da página de Troubleshooting.

Conclusão

O Ollama roda modelos abertos na sua máquina ou na nuvem com o mesmo fluxo de trabalho. Quatro pontos para levar:

• Confira a GPU antes de instalar: NVIDIA precisa de Compute Capability 5.0 ou superior; AMD, da lista do ROCm v7 ou do Vulkan; Macs, de um chip Apple série M. Rodando, confirme 100% GPU no ollama ps.
• Leia a tag antes de escolher: o que latest contém varia por modelo. Olhe o número do tamanho (e2b, 12b, 31b) e, na dúvida, escolha uma tag sem sufixo.
• Defina você o tamanho de contexto: abaixo de 24 GiB de VRAM, o padrão é 4k. Para agentes, recomenda-se pelo menos 64k; recupere memória quantizando o cache K/V.
• Conecte ferramentas pela API e pelo launch: as APIs compatíveis com OpenAI e Anthropic e o ollama launch permitem usá-lo nos seus apps e no Claude Code. Modelos pesados, com :cloud.

Comece abrindo o app ou digitando ollama run gemma4:e2b. O melhor jeito de aprender é deixá-lo rodando enquanto explora as diferenças em relação à nuvem e como escolher um modelo. Se quiser ir além e conectar um modelo ao seu editor para escrever código, programar com um LLM local mostra a configuração do Cline e do Continue.

FAQ