Laravel PHP command not found

Laravel PHP command not found

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

Stefan Bogdanescu

Founder & Senior Architect

Why "laravel: command not found" Happens and How to Fix It

Installing Laravel via Composer often feels seamless until you attempt to invoke the CLI directly. You run composer require laravel/installer without issue, yet when you type laravel new myapp, the terminal responds with -bash: laravel: command not found. This error isn't a bug in your installation; it is a shell environment variable configuration problem.

The underlying issue is path resolution. The laravel executable script resides within the Composer vendor directory, specifically at ~/.composer/vendor/bin/laravel. By default, your operating system's shell does not include this directory in its search path (PATH). Consequently, when you type a command, the shell scans only the directories listed in your PATH variable. Since ~/.composer/vendor/bin is missing from that list, the shell cannot locate the executable and returns the "command not found" error immediately.

To resolve this, you must explicitly add the vendor bin directory to your system's PATH. The approach differs slightly depending on whether you are using a Unix-based system (Linux, macOS) or Windows.

Updating the Shell Environment on macOS and Linux

On Unix-like systems, the standard method involves modifying your shell configuration file. This ensures the change persists across terminal sessions. You should edit the file that corresponds to your specific shell: ~/.zshrc for Zsh (default on modern macOS), ~/.bashrc or ~/.bash_profile for Bash, or ~/.profile.

Open your configuration file using a text editor like nano or vim:

nano ~/.zshrc

Locate the line defining the PATH variable. It often looks something like this:

export PATH="/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

You need to append the Composer bin directory to the end of this string. Add the following line before closing the quote or adding a new line if you prefer separate statements:

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

Note the use of $PATH at the end of the existing variable. This syntax appends your new directory to the end of the current search list. While this usually works, it introduces a potential trade-off regarding execution priority. If you have other tools named laravel or similar utilities installed in different directories (such as /usr/local/bin), the system will execute the first match found. By appending to the end, you ensure your Composer tools take precedence only if no earlier directory contains a matching executable. However, since laravel is unique to the installer, this priority concern is minimal for this specific tool.

After saving and closing the file, the changes do not take effect immediately. You must reload the shell configuration or open a new terminal window. Run the following command to apply the changes instantly:

source ~/.zshrc

Once the session is refreshed, verify the fix by running which laravel. This command should output the full path to your executable, confirming it is now discoverable.

Handling Windows Systems

Windows users face a similar constraint but must navigate the GUI or use PowerShell commands. Since Windows 10 and 11, you can add paths directly via the System Properties dialog. Open "Environment Variables" from the system settings and locate the Path variable in the System variables section. Click "Edit," then add the full path to your Composer bin directory (e.g., C:\Users\YourName\.composer\vendor\bin) as a new entry.

Alternatively, within PowerShell, you can prepend this directory to the PATH for the current session:

$env:Path += ";\$HOME\.composer\vendor\bin"

Remember that on Windows, the home directory usually expands to C:\Users\YourUsername. Ensure you use forward slashes or backslashes consistently with your shell's expectations.

Persistence and Common Pitfalls

A frequent mistake occurs when users add the path but forget to source the configuration file or restart their terminal session. The error persists until the shell re-reads the updated environment variables. Additionally, if you are using a package manager like Homebrew on macOS, ensure that your custom path doesn't conflict with system paths in an unexpected way, though Laravel's installer is generally isolated enough to avoid such conflicts.

Once configured, the laravel command will function indistinguishably from other global commands. You can now create new projects or run existing ones without needing to specify the full executable path every time. If you encounter issues later, remember that changing the PATH variable is the standard mechanism for integrating local tools into your development workflow.

Our network