Setting Up Laravel Valet on macOS: A Complete Guide with Troubleshooting

Laravel Valet is a lightweight and blazing-fast development environment for macOS. It allows developers to serve PHP applications, including Laravel projects, with minimal setup. Unlike Homestead or Docker, Valet runs directly on your Mac using Nginx and Dnsmasq, providing a seamless and efficient local development experience.

Why Use Laravel Valet?

• Lightweight & Fast – No need for virtual machines or heavy server stacks.
• Automatic Domain Resolution – Every project gets a .test domain automatically.
• SSL Support – Provides secure HTTPS out of the box.
• Multi-framework Support – Works with Laravel, WordPress, Symfony, and more.

Step-by-Step Installation Guide

Install Homebrew (If Not Installed)

Valet requires Homebrew, a package manager for macOS. If you haven’t installed it yet, run:

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

Then, update Homebrew:

brew update

Install PHP & Composer

Laravel Valet requires PHP and Composer. Install them using:

brew install php
brew install composer

Install Laravel Valet

Now, install Valet globally via Composer:

composer global require laravel/valet

**Common Issue:** If you see an error related to `Xdebug` or `Step Debug`, you can ignore it for now.

Add Valet to Your PATH

After installing Valet, you might run into an issue where the valet command is not found. To fix this, ensure your Composer global bin directory is in your system’s $PATH:

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

If you’re using bash, replace ~/.zshrc with ~/.bashrc.

Now, verify that Valet is installed by running:

which valet

If it returns a path like /Users/yourname/.composer/vendor/bin/valet, you’re good to go.

Install Valet

Run the installation command:

valet install

This will configure your system, set up Nginx, and Dnsmasq.

Park Your Projects

To serve your Laravel projects automatically, navigate to the folder where you store your projects (e.g., ~/Sites) and run:

cd ~/Sites
valet park

Now, any Laravel project inside this folder can be accessed using project-folder-name.test in your browser.

To serve a specific project without parking an entire directory, navigate to the project folder and run:

valet link myproject

Then, access it via myproject.test.

Common Issues & Fixes

valet: command not found

Fix: Ensure Valet is in your $PATH by running:

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

Then restart your terminal and try again.

brew: command not found

Fix: Homebrew might not be installed or configured correctly. Reinstall Homebrew and restart your terminal.

Valet Not Serving Sites Properly

If your .test domains are not resolving, try:

valet restart

Or, reinstall Valet:

valet uninstall
valet install

Issues with PHP Version

If Valet is using the wrong PHP version, switch to the correct version:

valet use [email protected]

Replace 8.2 with your preferred version.

Final Thoughts

Laravel Valet is an excellent tool for Mac users looking for a fast and minimal development setup. By following this guide, you can set up Valet, link your projects, and troubleshoot common issues efficiently.

Let me know in the comments if you encounter any issues or have additional tips for working with Laravel Valet!