zsh: command not found laravel

zsh: command not found laravel

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Why zsh: command not found Happens After Adding Composer Binaries

Encountering the zsh: command not found: laravel error immediately after installing Laravel's installer is a classic friction point for developers switching shells or managing environments on Linux and macOS. The issue isn't that the laravel binary was never installed; it is simply that the shell session currently running does not see the directory containing that binary in its search path.

The source material describes a scenario where a developer installs laravel/installer globally via Composer:

composer global require "laravel/installer"

Composer creates a local installation directory at ~/.composer/vendor/bin. Following this, the user adds the following line to their shell configuration file, specifically ~/.zshrc:

export PATH="$HOME/.composer/vendor/bin:$PATH"

At first glance, this seems correct. The user verifies that echo $PATH reflects the new entry at the beginning of the list. However, the command still fails. The root cause lies in how Zsh handles configuration files and when variables are expanded relative to file loading.

Shell Configuration Loading Order

In Unix-like systems, your shell reads configuration files sequentially upon startup. For Zsh, this typically involves ~/.zprofile, ~/.zshrc, and sometimes other dotfiles depending on your setup (like Oh My Zsh).

The critical detail often missed by beginners is the distinction between interactive login shells and non-interactive shells. When you start a new terminal window or tab, it usually behaves as a login shell. Login shells read ~/.zprofile (or /etc/zprofile) before they read ~/.zshrc.

If your system's default configuration places the global Composer bin path in ~/.zprofile, but your custom addition sits only in ~/.zshrc, you might expect it to work. However, if you are launching the terminal non-interactively (e.g., via a cron job or a script) or if your specific Zsh setup prioritizes ~/.zprofile differently, the order matters immensely.

More commonly in the "Oh My Zsh" ecosystem mentioned in the source material, users often find that the changes made to ~/.zshrc are not picked up by an existing terminal session. The shell has already read its configuration at startup. You must either restart the terminal or explicitly reload the configuration for the changes to take effect.

Reloading the Configuration

The most immediate fix is to source your configuration file again within the current session. Run the following command in your terminal:

source ~/.zshrc

Or, if you prefer to use the specific Zsh syntax for reloading:

. ~/.zshrc

Once executed, try running laravel again. If the binary is now found, the issue was purely a matter of timing—the shell hadn't re-evaluated the $PATH variable yet.

Verifying the Binary Location

If sourcing the file yields no change, you must verify exactly where the binary resides and ensure it matches the path in your configuration. You can locate the installed laravel executable using:

composer global show laravel/installer

This command outputs the installation directory. Compare this output with the path defined in your ~/.zshrc. Sometimes, users inadvertently modify the path to point to a generic ~/.composer/vendor/bin while the actual binary resides in a subdirectory or a slightly different location depending on the Composer version.

Ensure that the path added to $PATH is absolute or expands correctly relative to your home directory. Using ~ inside double quotes works, but ensure there are no extra spaces or characters that might break the expansion. For example:

export PATH="$HOME/.composer/vendor/bin:$PATH"

Potential Pitfalls with Oh My Zsh

Users running Oh My Zsh often encounter conflicts because the framework manages its own ~/.zshrc. While appending to the end of the file is generally safe, some plugins or themes might override certain variables later in the file execution. If your custom PATH export appears after a theme block that resets environment variables, your addition might get wiped out.

A robust approach is to append your exports at the very end of ~/.zshrc, ensuring they are evaluated last. Additionally, if you are using oh-my-zsh's functions or specific hooks, ensure no other part of your configuration is unsetting the $PATH.

Final Considerations

This error is rarely a sign of a broken installation; it is almost exclusively an environment variable scope issue. The binary exists, but the current shell process cannot find it before attempting to execute the command. By ensuring your ~/.zshrc is sourced after configuration changes and verifying the exact location of the Composer global binaries, you can resolve the command not found error without needing to reinstall Laravel or Composer.

For further documentation on managing these environments or advanced installation steps, refer to the official resources available at https://laravelcompany.com when you need verified guides for specific versions.

Our network