Homebrew para macOS

O instalador que transforma o Mac em um ambiente de desenvolvimento reproduzível.

Homebrew é o gerenciador de pacotes mais usado no macOS para instalar ferramentas de terminal, bibliotecas, runtimes e aplicativos. O valor dele não está apenas em “baixar programas”: está em resolver dependências, manter versões atualizadas, separar arquivos do sistema e tornar uma máquina reconstruível.

1. O que é o Homebrew

Homebrew é um sistema de distribuição e gerenciamento de software. Você declara o que quer instalar; ele baixa uma versão compatível, instala dependências, organiza os arquivos e cria os links necessários para que o comando fique disponível no terminal.

Ele não substitui o instalador da Apple, a App Store ou o atualizador interno de cada aplicativo. Ele complementa o macOS, principalmente para ferramentas que a Apple não inclui e para software de desenvolvimento.

2. Arquitetura e prefixos no Mac

O local recomendado depende da arquitetura:

• Apple Silicon — /opt/homebrew.
• Intel — /usr/local.

O prefixo padrão é uma decisão de compatibilidade, não apenas uma preferência estética. Ele permite usar bottles oficiais, evita misturar arquivos com o sistema e reduz a necessidade de sudo depois da instalação inicial.

brew --prefix
brew --prefix python
brew --cellar
brew --caskroom
brew --cache

Em Apple Silicon, um terminal rodando nativamente deve encontrar /opt/homebrew/bin/brew. Se o terminal estiver sob Rosetta, pode aparecer uma instalação Intel em /usr/local; manter duas instalações sem uma razão clara costuma causar confusão de PATH, versões e arquitetura.

3. Como instalar

Pré-requisitos

A documentação atual do Homebrew para macOS exige CPU Apple Silicon ou Intel 64-bit, hardware oficialmente suportado, macOS Sonoma 14 ou superior e Command Line Tools para Xcode ou Xcode. Confira sua situação:

sw_vers
uname -m
xcode-select -p

Se as Command Line Tools ainda não estiverem instaladas:

xcode-select --install

O instalador oficial

Use o comando publicado na página oficial do Homebrew e leia as mudanças que ele apresenta antes de confirmar:

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

O script instala no prefixo padrão, pede confirmação e mostra ao final o comando necessário para configurar o shell. Essa última parte é obrigatória: normalmente é um eval "$(.../bin/brew shellenv)" no arquivo de configuração do shell.

# Apple Silicon, normalmente em ~/.zprofile
 echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
 eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel, normalmente em ~/.zprofile
 echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
 eval "$(/usr/local/bin/brew shellenv)"

brew --version
brew doctor

4. O ciclo mental de uso

Quase toda operação cotidiana segue este fluxo:

1. Descobrir: brew search, brew info, página oficial do pacote.
2. Instalar: brew install para formula ou brew install --cask para aplicativo.
3. Verificar: brew list, command -v, brew info.
4. Manter: brew update, brew outdated, brew upgrade.
5. Limpar: brew autoremove e brew cleanup, após revisar o que será removido.

brew --version
brew help
brew commands
brew help install
brew help services

5. Pesquisar antes de instalar

brew search nginx
brew search --formula python
brew search --cask visual-studio-code
brew info python
brew info --cask visual-studio-code
brew desc python
brew home python

brew search procura nomes de formulae e casks, inclusive usando a informação online dos taps oficiais. brew info é mais importante para decidir: mostra descrição, versão estável, dependências, opções relevantes, localização e, para casks, detalhes do aplicativo e seus artefatos.

Quando o nome for ambíguo, não instale o primeiro resultado. Compare brew info formula, o site formulae.brew.sh e a documentação do projeto upstream.

6. Instalar ferramentas, bibliotecas e aplicativos

Formulae

brew install git
brew install wget jq ripgrep fd
brew install python@3.13
brew install postgresql@16 redis

Ao instalar uma formula, o Homebrew pode instalar outras formulae como dependências. Normalmente você não precisa adicionar cada dependência manualmente ao comando.

Casks

brew install --cask visual-studio-code
brew install --cask firefox rectangle
brew install --cask docker

Use o token exato exibido pelo brew search ou brew info --cask. O Homebrew não transforma todo aplicativo em “serviço”: instalar um cask apenas instala o aplicativo; inicialização automática, permissões e atualizadores podem seguir o comportamento próprio do app.

Depois da instalação

command -v jq
jq --version
brew list --versions
brew list --formula
brew list --cask

Formulae keg-only não são linkadas automaticamente no prefixo porque poderiam conflitar com software do sistema ou outra versão. Nesse caso, leia o aviso do instalador e prefira usar o caminho recomendado por brew info, em vez de forçar links às cegas.

7. Atualizar Homebrew e pacotes

# Atualizar definições e o próprio brew
brew update

# Ver o que está desatualizado
brew outdated
brew outdated --formula
brew outdated --cask

# Atualizar tudo
brew upgrade

# Atualizar apenas um pacote
brew upgrade jq
brew upgrade --cask firefox

brew update atualiza o conhecimento local de formulae, casks e do próprio Homebrew; brew upgrade aplica versões novas aos pacotes instalados. Separar os dois passos torna o processo observável e ajuda a evitar atualizações inesperadas.

Pin e auto-update

brew pin formula
brew list --pinned
brew unpin formula

# Somente para um comando
HOMEBREW_NO_AUTO_UPDATE=1 brew install formula

Pinning impede upgrades normais de uma formula, mas não é uma solução universal para congelar um ambiente. Uma dependência fixada pode ser necessária para outro pacote e precisar ser atualizada. Para reprodutibilidade real, use um Brewfile e, quando necessário, controle versões em um mecanismo apropriado.

8. Remover pacotes e limpar resíduos

# Remover uma formula
brew uninstall jq

# Remover um cask
brew uninstall --cask firefox

# Ver dependências que ficaram órfãs
brew autoremove --dry-run

# Remover órfãs confirmadas
brew autoremove

# Ver o que a limpeza removeria
brew cleanup --dry-run

# Limpar caches e versões antigas
brew cleanup

uninstall remove o pacote escolhido. autoremove mira formulae que foram instaladas somente como dependências e não são mais necessárias. cleanup remove versões antigas e downloads em cache conforme as regras do Homebrew.

Para casks, alguns aplicativos deixam preferências, caches ou dados de usuário. O modo mais agressivo é:

brew uninstall --cask --zap nome-do-cask

Se quiser remover todas as versões antigas de uma formula, existe brew uninstall --force formula; é destrutivo e deve ser reservado para casos entendidos, especialmente se a limpeza automática tiver sido desativada.

9. Inspeção, diagnóstico e manutenção

brew doctor
brew config
brew missing
brew linkage --test formula
brew uses --installed formula
brew deps formula
brew deps --tree formula
brew leaves
brew list --versions

• brew doctor: detecta problemas comuns de configuração.
• brew config: mostra arquitetura, versão, prefixo, shell e ambiente útil para suporte.
• brew missing: aponta dependências ausentes.
• brew deps --tree: transforma dependências em uma árvore legível.
• brew uses --installed: mostra quem depende de uma formula instalada.
• brew leaves: lista pacotes instalados explicitamente, ignorando dependências.

Ao pedir ajuda, inclua brew config, brew doctor e o comando que falhou. Não publique tokens, chaves ou caminhos que revelem dados sensíveis sem revisar a saída.

10. Links, versões e múltiplos runtimes

brew unlink python@3.12
brew link python@3.13
brew link --overwrite formula
brew info python@3.13
brew list --versions python

link controla links simbólicos no prefixo; unlink os remove sem desinstalar a formula. Só use --overwrite depois de entender quais arquivos serão substituídos.

Para runtimes versionados, como Python, Node ou PostgreSQL, escolha explicitamente a versão na instalação e verifique o binário realmente usado:

which -a python3
python3 --version
which -a node
node --version
brew --prefix python@3.13

Também é possível usar caminhos completos ou gerenciadores específicos do ecossistema. Homebrew instala o runtime; ele não decide sozinho a estratégia de ambientes virtuais, versões por projeto ou dependências do seu código.

11. Taps e fontes adicionais

brew tap
brew tap user/repo
brew untap user/repo
brew tap-info --json user/repo

Os taps oficiais de core e cask são a base normal. Um tap de terceiros pode fornecer software que não está nos repositórios oficiais, mas adiciona uma nova cadeia de confiança. Leia o repositório, mantenedor, fórmula e código antes de usar em máquinas de produção.

Também existe brew install --HEAD formula para instalar a versão de desenvolvimento quando a formula oferece esse caminho. Isso é útil para testar uma correção, mas menos previsível do que uma versão estável e pode exigir compilação local.

12. Brewfile: reproduzir um Mac

O Brewfile registra formulae, casks, taps e outros tipos de dependência suportados pelo Homebrew Bundle. É uma forma simples de versionar o ambiente de uma máquina e reconstruí-lo em outra.

# Criar um inventário do estado atual
brew bundle dump --force

# Instalar/alinhar a máquina ao Brewfile
brew bundle install

# Verificar sem instalar
brew bundle check

# Mostrar tudo que o arquivo declara
brew bundle list --all

Um exemplo mínimo:

tap "homebrew/cask-fonts"
brew "git"
brew "jq"
brew "python@3.13"
cask "visual-studio-code"
cask "rectangle"

Coloque o arquivo sob controle de versão, mas revise o resultado do dump. Ele representa o estado instalado, que pode incluir itens temporários ou específicos de uma máquina. Para reproduzir somente o que é realmente necessário, edite-o conscientemente.

13. Segurança e boas práticas

• Instale pelo script oficial de brew.sh ou pelo release oficial; desconfie de scripts de terceiros.
• Leia o que um comando de instalação vai fazer antes de confirmar, principalmente casks e taps externos.
• Evite sudo brew; corrija o prefixo e as permissões.
• Não use --force, --overwrite ou --zap como tentativa genérica de resolver erro.
• Faça brew update e brew upgrade em um momento controlado, principalmente antes de uma entrega.
• Não confunda “instalado pelo Homebrew” com “confiável”: a origem upstream e o tap importam.
• Em máquinas corporativas, prefira automação auditável, usuário correto e inventário via Brewfile.

14. Receitas práticas

Preparar um Mac de desenvolvimento

brew update
brew install git jq ripgrep fd wget
brew install --cask visual-studio-code rectangle
brew bundle dump --force
brew doctor

Descobrir e instalar uma ferramenta

brew search imagemagick
brew info imagemagick
brew install imagemagick
command -v magick
magick --version

Manutenção conservadora

brew update
brew outdated
brew upgrade --dry-run
brew cleanup --dry-run
brew doctor

Se a sua versão não aceitar uma opção de simulação para uma subcomando específico, consulte brew help nome-do-comando; a disponibilidade de flags varia por comando e versão.

15. brew services em profundidade

brew services é a camada do Homebrew para administrar processos de longa duração instalados por uma formula — por exemplo, PostgreSQL, Redis, Nginx, MySQL ou um servidor de desenvolvimento. Ele não é um gerenciador de pacotes separado: usa as definições de serviço fornecidas pela formula e conversa com o gerenciador nativo do sistema.

O que ele controla no macOS

No macOS, o Homebrew Services usa o launchctl, o gerenciador de daemons e agentes da Apple:

• Agente do usuário — normalmente fica em ~/Library/LaunchAgents e roda no contexto do usuário que executou o comando. É o modo normal para um ambiente de desenvolvimento.
• Daemon do sistema — quando usado com sudo, opera em /Library/LaunchDaemons e é associado ao boot do sistema, não ao login de um usuário específico.

Essa distinção explica por que um serviço iniciado sem sudo pertence ao seu usuário, pode acessar arquivos desse usuário e normalmente inicia no login; o modo com sudo tem outra responsabilidade operacional e outro conjunto de permissões.

# Ver o contexto e os caminhos do Homebrew
brew --prefix
brew services list

# Ver a ajuda da versão instalada
brew help services
brew services --help
brew services start --help

Preparar e descobrir um serviço

Primeiro instale a formula e descubra o nome correto do serviço:

brew search postgresql
brew info postgresql@16
brew install postgresql@16
brew services list

Uma formula pode declarar um serviço com um nome diferente do nome mais intuitivo do pacote. Por isso, prefira o nome mostrado em brew services list ou indicado por brew info. Exemplos comuns:

brew install postgresql@16
brew install redis
brew install nginx

brew services list

Se a fórmula não tiver definição de serviço, o Homebrew não terá o que controlar. Nesse caso, a instalação do pacote pode estar correta, mas brew services start nome não será a ferramenta apropriada.

Listar estado: list

brew services list
brew services list --json
brew services list --debug

A lista mostra, entre outros dados, nome, status, usuário e arquivo de serviço carregado. Os estados mais úteis são:

A saída JSON é útil para automação:

brew services list --json | jq .
brew services list --json > services-status.json

Iniciar e registrar: start

brew services start postgresql@16
brew services start redis
brew services start nginx

start inicia imediatamente e registra o serviço para ser iniciado automaticamente no próximo login do usuário — ou no boot, quando executado no contexto de daemon do sistema. É o comando que normalmente você quer para um serviço local persistente.

Depois de iniciar, valide em camadas:

brew services list
brew services info postgresql@16
ps aux | grep '[p]ostgres'
lsof -nP -iTCP:5432 -sTCP:LISTEN
pg_isready

Nem todo processo expõe a mesma porta ou possui um comando de health check. Consulte brew info nome e a documentação do software para descobrir a porta, arquivo de configuração e teste adequado.

Executar apenas agora: run

brew services run postgresql@16
brew services run redis
brew services run nginx

run executa o serviço sem registrá-lo para iniciar automaticamente no login ou boot. É ideal para testes temporários, depuração ou quando você quer controlar manualmente o ciclo de vida.

Parar: stop, stop --keep e kill

# Para e remove o registro de inicialização
brew services stop redis

# Para, mas mantém o registro para o próximo login/boot
brew services stop redis --keep

# Para imediatamente, mantendo o serviço registrado
brew services kill redis

# Operações em todos os serviços do contexto atual
brew services stop --all
brew services kill --all

stop é a opção normal para desligar de forma organizada e deixar o serviço desativado. A implementação atual espera, por padrão, até 60 segundos para o processo terminar; você pode ajustar o comportamento:

# Não esperar o encerramento
brew services stop redis --no-wait

# Esperar no máximo 10 segundos
brew services stop redis --max-wait=10

# Ver opções exatas da sua versão
brew help services

kill é diferente: para imediatamente, mas preserva o registro de inicialização. Use-o para um processo travado ou quando você precisa interromper sem desfazer o agendamento.

Reiniciar e atualizar o arquivo de serviço

brew services restart redis
brew services restart postgresql@16
brew services restart nginx
brew services restart --all

restart para o serviço, quando necessário, e inicia novamente, mantendo o registro de login/boot. Ele é especialmente importante depois de uma atualização do pacote: a formula pode ter produzido uma nova definição de serviço, e o restart recarrega essa configuração.

Para testar uma definição específica de serviço:

brew services start redis --file=/caminho/para/redis.plist
brew services run redis --file=/caminho/para/redis.plist
brew services restart redis --file=/caminho/para/redis.plist

Use --file com cuidado: você deixa de usar o arquivo gerado normalmente pela formula e passa a operar uma definição explícita.

Detalhar com info

brew services info redis
brew services info redis --verbose
brew services info --all
brew services info redis --json | jq .

info é mais detalhado que list. Dependendo do modo, ele informa se está rodando, carregado, agendável, usuário, PID, arquivo, comando, diretório de trabalho, diretório raiz, caminho de log, caminho de erro, intervalo e cron.

Para diagnosticar um serviço, compare três coisas:

1. o estado visto por brew services list;
2. o arquivo e o comando vistos em brew services info --verbose;
3. a execução direta do servidor com os mesmos argumentos, para separar problema do aplicativo de problema do launchd.

Onde ficam os arquivos

Os arquivos são gerados pelo Homebrew e carregados pelo launchctl. Em uma instalação de usuário, procure normalmente em:

ls -la ~/Library/LaunchAgents
find ~/Library/LaunchAgents -maxdepth 1 -iname '*homebrew*' -print

# Consultar o domínio do usuário via launchctl
launchctl list
launchctl print gui/$(id -u)

Em modo de sistema, o arquivo costuma estar em /Library/LaunchDaemons:

sudo ls -la /Library/LaunchDaemons
sudo launchctl list

Não edite o plist gerado como solução permanente: uma atualização ou restart pode recriá-lo. Configure o software em seu arquivo próprio, use as opções documentadas pela formula ou crie conscientemente uma definição personalizada com --file.

Usuário, permissões e sudo

Sem sudo, o serviço roda como seu usuário. Isso normalmente é o comportamento mais seguro e previsível para desenvolvimento. Com sudo, o Homebrew pode registrar o serviço como daemon do sistema:

# Usuário atual: inicia no login
brew services start redis

# Sistema: inicia no boot; exige decisão explícita
sudo brew services start redis

Rodar como root altera acesso a arquivos, diretórios de dados, sockets, portas privilegiadas e variáveis de ambiente. Um servidor que funcionava como seu usuário pode falhar como root — ou criar arquivos que depois seu usuário não consegue modificar.

Quando o Homebrew é invocado por uma ferramenta de administração de Macs como root, existe também a opção específica:

sudo brew services --sudo-service-user=usuario start nome

Use essa forma somente em automação administrada e documentada. Ela não é um atalho para corrigir permissões de uma instalação pessoal.

Logs e diagnóstico de falhas

Quando um serviço aparece como error ou inicia e morre imediatamente, siga uma ordem curta:

brew services list --debug
brew services info nome --verbose
brew info nome
brew services restart nome

# Ver mensagens recentes do launchd
log show --last 10m --predicate 'process == "launchd"' --info

# Ver processos e portas
ps aux | grep '[n]ome'
lsof -nP -iTCP -sTCP:LISTEN

Depois execute o servidor fora do Homebrew Services, usando o comando indicado por brew services info --verbose ou pela documentação do pacote. Erros como “porta ocupada”, diretório de dados inexistente, configuração inválida, versão incompatível ou permissões inadequadas geralmente aparecem com mais clareza na execução direta.

Confira também caminhos de log indicados no info --verbose. Não presuma que todo serviço grava em um arquivo igual: alguns usam stdout/stderr redirecionados pelo launchd, outros escrevem em seu próprio diretório de dados.

Limpar registros órfãos: cleanup

brew services cleanup
sudo brew services cleanup

cleanup remove serviços não utilizados e arquivos de serviço órfãos no contexto corrente. Execute primeiro sem sudo; use a forma administrativa somente para limpar registros pertencentes ao sistema.

O significado de --all

O parâmetro --all opera em todos os serviços encontrados no contexto. Ele não significa “todos os processos do Mac” nem “todos os pacotes instalados”. Use-o com prudência:

brew services list
brew services stop --all
brew services start --all
brew services restart --all

Em especial, stop --all pode interromper banco de dados e outras dependências de projetos diferentes. Prefira indicar o nome do serviço quando você souber qual processo quer controlar.

Exemplos completos

PostgreSQL local

brew install postgresql@16
brew services start postgresql@16
brew services list
brew services info postgresql@16 --verbose
pg_isready
psql postgres

Se precisar apenas de uma sessão temporária de teste, troque start por run. O diretório de dados, a porta e o nome do binário podem variar conforme a versão da formula.

Redis local

brew install redis
brew services start redis
redis-cli ping
brew services restart redis
brew services stop redis

Nginx local

brew install nginx
brew services start nginx
brew services info nginx --verbose
curl -I http://127.0.0.1:8080
brew services stop nginx

A porta padrão do Nginx instalado pelo Homebrew frequentemente não é a porta 80, porque portas abaixo de 1024 exigem privilégios especiais. Confirme sempre a configuração efetiva antes de testar.

Serviços temporários com brew bundle

O Homebrew Bundle possui uma integração opcional: brew bundle exec --services comando pode iniciar temporariamente os serviços declarados no Brewfile enquanto o comando roda. Isso é diferente de registrar serviços permanentemente com brew services start.

HOMEBREW_BUNDLE_SERVICES=1 brew bundle exec --services ./testes.sh
brew bundle sh --services

Esse padrão é útil para testes locais que precisam de PostgreSQL ou Redis, mas deve ser validado no seu fluxo: serviços temporários, dados persistentes e cleanup podem exigir tratamento próprio.

Checklist de operação

1. O pacote está instalado? brew info nome.
2. A formula oferece serviço? Verifique a informação e a lista.
3. Você quer persistência no login/boot? Use start; caso contrário, considere run.
4. O serviço está no contexto correto? Compare usuário, sudo e caminho do plist.
5. Está rodando? Use list, PID, processo, porta e health check.
6. Falhou? Use info --verbose, --debug, logs e execução direta.
7. Foi removido o pacote, mas sobrou registro? Use brew services cleanup.

16. Cheat sheet

Fontes oficiais consultadas

• Homebrew — página oficial
• Homebrew Documentation — Installation
• Homebrew Documentation — brew(1) Manpage
• Homebrew Documentation — FAQ
• Homebrew Formulae — catálogo de formulae e casks
• Homebrew/install — instalador e desinstalador
• Homebrew/brew — comando services
• Homebrew/brew — subcomandos de services