Instala primeiro o instalador com composer global require laravel/installer, depois pergunta ao Composer onde coloca os seus executáveis: composer global config bin-dir --absolute. Acrescenta esse caminho à tua PATH no ~/.zshrc, depois source ~/.zshrc. Em macOS com bash, o ficheiro é o ~/.bash_profile, nunca o ~/.bashrc.
Escreves laravel new meu-projeto e o terminal responde:
zsh: command not found: laravelO problema quase nunca é o Laravel. É que o executável instalado pelo Composer está numa pasta que a tua shell não consulta. É preciso, portanto, encontrar essa pasta e depois acrescentá-la à PATH.
Artigo do percurso Desenvolvimento web. Procedimento verificado a 2 de setembro de 2026 em macOS 26.5.1 com Composer 2.9.5 e zsh.
Primeiro: o instalador está instalado?
O comando laravel não vem com o Composer, instala-se à parte:
composer global require laravel/installerSe nunca o correste, nenhum acerto na PATH fará aparecer o comando. Repara que podes muito bem passar sem ele: composer create-project laravel/laravel meu-projeto faz o mesmo sem instalador global.
Encontrar a pasta certa, sem adivinhar
A maioria dos tutoriais manda-te copiar $HOME/.composer/vendor/bin. Muitas vezes está certo, mas nem sempre: o Composer escolhe a sua pasta pessoal consoante o sistema e as variáveis de ambiente presentes. Em vez de apostar, pergunta-lhe:
composer global config bin-dir --absolute/Users/gekkode/.composer/vendor/binÉ o resultado obtido em macOS 26.5.1. Numa instalação configurada para seguir as convenções XDG, o comando pode devolver ~/.config/composer/vendor/bin. Usa sempre o que o comando mostra na tua máquina, não o que diz um tutorial.
Enquanto não houver um pacote global instalado, o caminho está correto mas a pasta não existe. Não tem consequências: acrescentar à PATH uma pasta inexistente não provoca qualquer erro, e ela será criada no primeiro composer global require.
Acrescentar a pasta à PATH com zsh
A zsh é a shell por omissão do macOS desde o Catalina. O ficheiro a alterar é o ~/.zshrc:
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcSubstitui o caminho por aquele que o comando anterior te devolveu. O source aplica a alteração à sessão atual, sem ele, só produzirá efeito num novo terminal.
Confirma:
which laravel
laravel --versionE se usares a bash
Em macOS Mojave e anteriores, ou se mantiveste a bash de propósito, o ficheiro é o ~/.bash_profile:
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profileÉ o erro clássico, e estava na versão anterior deste artigo. Em macOS, o Terminal abre uma login shell, que lê o ~/.bash_profile e não o ~/.bashrc. Uma linha acrescentada ao ~/.bashrc nunca será aplicada, o que dá a impressão de que a manobra não funciona.
Para saberes que shell estás a usar:
echo $SHELL
# /bin/zsh → ~/.zshrc
# /bin/bash → ~/.bash_profileSe o comando continuar por encontrar
Três verificações, por esta ordem. Primeiro, a PATH contém mesmo a pasta:
echo $PATH | tr ':' '\n' | grep composerDepois, o executável está lá:
ls "$(composer global config bin-dir --absolute)"Se não estiver, a instalação global falhou. Volta a lançá-la e lê o que sai: um conflito de versão do PHP é a causa mais frequente.
Por fim, se for o próprio Composer que não aparece, é o mesmo problema um nível abaixo. Em macOS, a instalação mais simples passa pelo Homebrew:
brew install composerNum servidor, a questão não se coloca nos mesmos termos: vê a instalação do Composer em Debian.
A alternativa que faz o problema desaparecer
O Laravel Herd instala o PHP, o Composer e o instalador do Laravel num ambiente gerido, e trata ele próprio da PATH. Para uma máquina de desenvolvimento macOS montada de raiz, é o caminho mais curto: deixa de haver ficheiro de configuração da shell para mexer.
Se já trabalhas com uma instalação Homebrew que dominas, a manobra sobre a PATH descrita acima continua perfeitamente válida.
Erros frequentes
~/.bash_profile. Uma linha acrescentada ao ~/.bashrc nunca é aplicada.composer global config bin-dir --absolute dá o caminho certo na tua máquina.source sobre o ficheiro alterado.
