Laravel Valet – Installation & Setup Guide (macOS)

Laravel Valet is a lightweight development environment for macOS. It configures your Mac to run Nginx in the background and uses DnsMasq to proxy all requests on the *.test domain to your local machine.

Prerequisites

macOS
Homebrew installed

Installation

1. Install PHP

brew install php

2. Install Composer

brew install composer

3. Add Composer's global bin to your PATH

Since you're using zsh (default on modern macOS), edit your ~/.zshrc:

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

Note: Older Composer versions use ~/.composer/vendor/bin, newer ones use ~/.config/composer/vendor/bin. Adding both ensures it works regardless.

Verify with:

echo $PATH

4. Install Valet via Composer

composer global require laravel/valet

5. Run Valet install

valet install

This sets up Nginx, DnsMasq, and registers Valet to launch on system startup.

Verify installation:

which valet
# Should output something like: /Users/<you>/.composer/vendor/bin/valet

Where Valet Lives (Installation Directory & Config)

Valet stores its configuration and site data in ~/.config/valet/:

~/.config/valet/
├── config.json          # Main config (TLD, paths, PHP version)
├── dnsmasq.d/           # DnsMasq configuration
├── Drivers/             # Custom Valet drivers
├── Extensions/          # Valet extensions
├── Log/                 # Nginx & PHP logs
├── Nginx/               # Per-site Nginx configs
├── Sites/               # Linked sites registry
└── Certificates/        # SSL certs for secured sites

Changing the TLD (default: `.test`)

valet tld local
# Now sites are served at *.local instead of *.test

Viewing current config

cat ~/.config/valet/config.json

Setting Up Your Sites Directory

The recommended approach is to create a dedicated directory in your home folder:

# Create a Sites directory in your home folder
mkdir -p ~/Sites

# Park it with Valet (all subdirectories become sites)
cd ~/Sites
valet park

Now every folder inside ~/Sites is automatically served:

~/Sites/my-project → http://my-project.test
~/Sites/client-site → http://client-site.test

View all parked paths

valet paths

Remove a parked path

cd ~/Sites
valet forget

Database Setup

Valet doesn't include a database server. Choose one of the options below.

MariaDB vs MySQL — what's different?

For local WordPress development, nothing changes in practice. MariaDB is a drop-in replacement for MySQL:

Same SQL syntax, same port (3306), same default credentials

WordPress wp-config.php uses the same DB_HOST, DB_USER, DB_PASSWORD settings

WP-CLI commands work identically

phpMyAdmin works with both without any config changes

The mysql CLI command works with both (MariaDB aliases it)

Pick whichever you prefer. Do not install both — they conflict on port 3306.

Option A: MariaDB (recommended)

brew install mariadb
brew services start mariadb

Default credentials after install:

Host: 127.0.0.1
User: root
Password: (empty)
Port: 3306

Secure the installation

Set a root password and remove test databases:

mariadb-secure-installation

After securing, if you set a root password, use -p flag: mariadb -u root -p

Useful commands

# Log in
mariadb -u root -p

# Create a database
mariadb -u root -p -e "CREATE DATABASE my_site_db;"

# List all databases
mariadb -u root -p -e "SHOW DATABASES;"

# Drop a database
mariadb -u root -p -e "DROP DATABASE my_site_db;"

# Check status
brew services info mariadb

Start/Stop/Restart

brew services start mariadb
brew services stop mariadb
brew services restart mariadb

Option B: MySQL

brew install mysql
brew services start mysql

Default credentials after install:

Host: 127.0.0.1
User: root
Password: (empty)
Port: 3306

Secure the installation

mysql_secure_installation

After securing, if you set a root password, use -p flag: mysql -u root -p

Useful commands

# Log in
mysql -u root

# Create a database
mysql -u root -e "CREATE DATABASE my_site_db;"

# List all databases
mysql -u root -e "SHOW DATABASES;"

# Drop a database
mysql -u root -e "DROP DATABASE my_site_db;"

# Check status
brew services info mysql

Start/Stop/Restart

brew services start mysql
brew services stop mysql
brew services restart mysql

phpMyAdmin Setup

phpMyAdmin gives you a web UI to manage all your databases. We'll serve it through Valet.

1. Create a directory for phpMyAdmin

cd ~/Sites
mkdir phpmyadmin
cd phpmyadmin

2. Download phpMyAdmin

composer create-project phpmyadmin/phpmyadmin .

3. Create the config file

cp config.sample.inc.php config.inc.php

4. Edit the config

Open ~/Sites/phpmyadmin/config.inc.php and update:

<?php
/* Server configuration */
$cfg['Servers'][1]['host'] = '127.0.0.1';
$cfg['Servers'][1]['auth_type'] = 'cookie';
$cfg['Servers'][1]['AllowNoPassword'] = true;

/* Blowfish secret (must be 32 chars for cookie auth) */
$cfg['blowfish_secret'] = 'your-32-character-random-string-here';

Generate a random 32-char string:

openssl rand -base64 32

5. Access phpMyAdmin

Since ~/Sites is parked, phpMyAdmin is already available at:

http://phpmyadmin.test

Username: root
Password: (empty, or whatever you set during mariadb-secure-installation)

6. Optional: Secure with HTTPS

valet secure phpmyadmin

Now at: https://phpmyadmin.test

Updating phpMyAdmin

cd ~/Sites/phpmyadmin
composer update

Creating a New WordPress Site (Full Workflow)

1. Install WP-CLI

brew install wp-cli

2. Create the site directory

cd ~/Sites
mkdir my-wp-site
cd my-wp-site

3. Download WordPress

wp core download

4. Create the database

mariadb -u root -p -e "CREATE DATABASE my_wp_site;"

5. Create wp-config.php

wp config create \
  --dbname=my_wp_site \
  --dbuser=root \
  --dbpass="your_password" \
  --dbhost=127.0.0.1

6. Install WordPress

wp core install \
  --url="http://my-wp-site.test" \
  --title="My WP Site" \
  --admin_user=admin \
  --admin_password=password \
  --admin_email=admin@example.com

7. Done!

If ~/Sites is already parked, your site is live at: http://my-wp-site.test

Admin panel: http://my-wp-site.test/wp-admin

Optional: Enable HTTPS

valet secure my-wp-site

Now accessible at: https://my-wp-site.test

Update the URL in WordPress:

wp option update siteurl "https://my-wp-site.test"
wp option update home "https://my-wp-site.test"

Quick Script: Create a New WP Site in One Go

Save this as ~/Scripts/new-wp-site.sh and make it executable:

#!/bin/bash

# Usage: ./new-wp-site.sh site-name

SITE_NAME=$1
SITES_DIR="$HOME/Sites"
DB_NAME=$(echo "$SITE_NAME" | tr '-' '_')

if [ -z "$SITE_NAME" ]; then
  echo "Usage: ./new-wp-site.sh site-name"
  exit 1
fi

echo "Creating WordPress site: $SITE_NAME"

# Create directory
mkdir -p "$SITES_DIR/$SITE_NAME"
cd "$SITES_DIR/$SITE_NAME"

# Download WordPress
wp core download

# Create database
mariadb -u root -e "CREATE DATABASE IF NOT EXISTS $DB_NAME;"

# Create config
wp config create \
  --dbname="$DB_NAME" \
  --dbuser=root \
  --dbpass="" \
  --dbhost=127.0.0.1

# Install WordPress
wp core install \
  --url="http://$SITE_NAME.test" \
  --title="$SITE_NAME" \
  --admin_user=admin \
  --admin_password=password \
  --admin_email=admin@example.com

# Secure with HTTPS
valet secure "$SITE_NAME"

# Update URLs for HTTPS
wp option update siteurl "https://$SITE_NAME.test"
wp option update home "https://$SITE_NAME.test"

echo ""
echo "✅ Site ready at: https://$SITE_NAME.test"
echo "   Admin: https://$SITE_NAME.test/wp-admin"
echo "   User: admin / Password: password"
echo "   DB: $DB_NAME (view at https://phpmyadmin.test)"

Make it executable:

mkdir -p ~/Scripts
chmod +x ~/Scripts/new-wp-site.sh

Usage:

~/Scripts/new-wp-site.sh client-project

Serving Sites

Option A: Park a directory

Serves all subdirectories as individual sites:

cd ~/Sites
valet park

Any folder inside ~/Sites becomes accessible at http://folder-name.test.

Option B: Link a single project

For projects outside your parked directory:

cd ~/some/other/path/my-project
valet link my-project

Accessible at http://my-project.test.

List all linked sites

valet links

Remove a link

valet unlink my-project

Common Commands

Command	Description
`valet park`	Register current directory for serving
`valet forget`	Unpark the current directory
`valet paths`	View all parked paths
`valet link [name]`	Serve current directory at `name.test`
`valet links`	List all linked sites
`valet unlink [name]`	Remove a link
`valet secure [name]`	Serve a site over HTTPS
`valet unsecure [name]`	Revert to HTTP
`valet share`	Share your site publicly via a tunnel
`valet restart`	Restart Valet services
`valet stop`	Stop all Valet services
`valet start`	Start Valet services
`valet use php@8.2`	Switch PHP version
`valet tld [tld]`	Change the TLD (default: test)
`valet log`	View Valet logs
`valet which`	Show which Valet driver serves current site

Switching PHP Versions

# Install another PHP version
brew install php@8.1

# Tell Valet to use it
valet use php@8.1

# Switch back
valet use php@8.3

Per-site PHP version (Valet 4+)

Create a .valetphprc file in your site root:

echo "php@8.1" > ~/Sites/legacy-project/.valetphprc

Deleting a WordPress Site

# Remove the link/site
valet unlink my-wp-site
# or if using park, just delete the folder

# Drop the database
mariadb -u root -e "DROP DATABASE my_wp_site;"

# Remove the directory
rm -rf ~/Sites/my-wp-site

# Remove SSL cert if secured
valet unsecure my-wp-site

Troubleshooting

Valet command not found:

# Check if composer bin is in PATH
echo $PATH | tr ':' '\n' | grep composer

# If not, re-add it
echo 'export PATH="$HOME/.composer/vendor/bin:$HOME/.config/composer/vendor/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Sites not resolving:

valet restart
# or
sudo valet restart

Ping test:

ping anything.test
# Should resolve to 127.0.0.1

Check service status:

brew services list

MariaDB "Access denied for root" (ERROR 1698):

This happens when MariaDB uses unix_socket authentication for root (common on Linux installs). Only the system root user can log in as MariaDB root.

Quick fix — use sudo:

sudo mariadb -u root

Permanent fix — switch root to password auth:

sudo mariadb -u root

ALTER USER 'root'@'localhost' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;
EXIT;

Now log in without sudo:

mariadb -u root -p

Alternative — create a dedicated dev user (recommended):

sudo mariadb -u root

CREATE USER 'dev'@'localhost' IDENTIFIED BY 'dev';
GRANT ALL PRIVILEGES ON *.* TO 'dev'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Then use dev / dev as credentials in wp-config.php and WP-CLI commands:

mariadb -u dev -pdev
wp config create --dbuser=dev --dbpass=dev ...

MariaDB won't start:

brew services restart mariadb
# Check logs
cat /opt/homebrew/var/mysql/*.err

MySQL won't start:

brew services restart mysql
# Check logs
cat /opt/homebrew/var/mysql/*.err

Permission issues:

sudo valet trust

phpMyAdmin shows "Access denied":

Make sure AllowNoPassword is set to true in config.inc.php, or use the password you set during mariadb-secure-installation.

Uninstalling Valet

valet stop
valet uninstall
composer global remove laravel/valet
brew uninstall nginx dnsmasq

ajithrn/laravel-valet-setup.md

Laravel Valet – Installation & Setup Guide (macOS)

Prerequisites

Installation

1. Install PHP

2. Install Composer

3. Add Composer's global bin to your PATH

4. Install Valet via Composer

5. Run Valet install

Where Valet Lives (Installation Directory & Config)

Changing the TLD (default: .test)

Viewing current config

Setting Up Your Sites Directory

View all parked paths

Remove a parked path

Database Setup

Option A: MariaDB (recommended)

Secure the installation

Useful commands

Start/Stop/Restart

Option B: MySQL

Secure the installation

Useful commands

Start/Stop/Restart

phpMyAdmin Setup

1. Create a directory for phpMyAdmin

2. Download phpMyAdmin

3. Create the config file

4. Edit the config

5. Access phpMyAdmin

6. Optional: Secure with HTTPS

Updating phpMyAdmin

Creating a New WordPress Site (Full Workflow)

1. Install WP-CLI

2. Create the site directory

3. Download WordPress

4. Create the database

5. Create wp-config.php

6. Install WordPress

7. Done!

Optional: Enable HTTPS

Quick Script: Create a New WP Site in One Go

Serving Sites

Option A: Park a directory

Option B: Link a single project

List all linked sites

Remove a link

Common Commands

Switching PHP Versions

Per-site PHP version (Valet 4+)

Deleting a WordPress Site

Troubleshooting

Uninstalling Valet

References

Changing the TLD (default: `.test`)