„laravel: command not found” na macOS – jak to naprawić

Wpisujesz laravel new mon-projet, a terminal odpowiada:

zsh: command not found: laravel

Problem prawie nigdy nie leży po stronie Laravela. Rzecz w tym, że plik wykonywalny zainstalowany przez Composera leży w katalogu, do którego twój shell nie zagląda. Trzeba więc znaleźć ten katalog i dopisać go do PATH.

Artykuł ze ścieżki Programowanie webowe. Procedura sprawdzona 2 września 2026 roku na macOS 26.5.1 z Composerem 2.9.5 i zsh.

Najpierw: czy instalator w ogóle jest zainstalowany?

Polecenie laravel nie przychodzi razem z Composerem, instaluje się je osobno:

composer global require laravel/installer

Jeśli nigdy go nie uruchomiłeś, żadne ustawienie PATH nie sprawi, że polecenie się pojawi. Zauważ, że spokojnie możesz się bez niego obejść: composer create-project laravel/laravel mon-projet robi to samo bez globalnego instalatora.

Znajdź właściwy katalog, bez zgadywania

Większość poradników każe skopiować $HOME/.composer/vendor/bin. Często się to zgadza, ale nie zawsze: Composer wybiera swój katalog domowy zależnie od systemu i od obecnych zmiennych środowiskowych. Zamiast obstawiać, zapytaj go:

composer global config bin-dir --absolute

/Users/gekkode/.composer/vendor/bin

Taki wynik daje macOS 26.5.1. Na instalacji ustawionej pod konwencje XDG polecenie może zwrócić ~/.config/composer/vendor/bin. Zawsze używaj tego, co polecenie wypisze u ciebie, a nie tego, co mówi poradnik.

Dopisanie katalogu do PATH w zsh

zsh jest domyślnym shellem macOS od czasów Cataliny. Plik do zmiany to ~/.zshrc:

echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Podmień ścieżkę na tę, którą zwróciło poprzednie polecenie. source stosuje zmianę do bieżącej sesji, bez niego zadziała dopiero w nowym terminalu.

Sprawdź:

which laravel
laravel --version

A jeśli używasz bash

Na macOS Mojave i starszych, albo jeśli świadomie zostałeś przy bashu, plikiem jest ~/.bash_profile:

echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Żeby sprawdzić, jakiego shella używasz:

echo $SHELL
# /bin/zsh  →  ~/.zshrc
# /bin/bash →  ~/.bash_profile

Jeśli polecenia nadal nie widać

Trzy sprawdzenia po kolei. Najpierw: czy PATH naprawdę zawiera ten katalog:

echo $PATH | tr ':' '\n' | grep composer

Potem: czy plik wykonywalny w ogóle tam jest:

ls "$(composer global config bin-dir --absolute)"

Jeśli go nie ma, instalacja globalna się nie powiodła. Uruchom ją ponownie i przeczytaj wynik: najczęstszą przyczyną jest konflikt wersji PHP.

Wreszcie, jeśli to sam Composer jest nie do znalezienia, masz ten sam problem o poziom niżej. Na macOS najprościej zainstalować go przez Homebrew:

brew install composer

Na serwerze pytanie stawia się inaczej: zobacz instalację Composera na Debianie.

Alternatywa, która usuwa problem

Laravel Herd instaluje PHP, Composera i instalator Laravela w zarządzanym środowisku i sam zajmuje się PATH. Na stanowisku deweloperskim macOS stawianym od zera to najkrótsza droga: nie ma już żadnego pliku konfiguracyjnego shella do ruszania.

Jeśli pracujesz już na instalacji z Homebrew, którą masz pod kontrolą, opisana wyżej operacja na PATH pozostaje w pełni aktualna.