April 10, 2019/by Dave Macaulay

The easiest way to install Magento 2 on macOS using Valet+

Setting up Magento 2 can be pretty painful for several different reasons; however, it doesn't have to be. There's a great tool by the guys over at WeProvide that enables anyone developing on macOS to quickly set up a blazing fast Magento 2 instance on their local machine. It also allows you to set up other software in a similarly straightforward fashion.

A number of us internally here at Magento are using this exact setup for our day to day development. Working with this setup is incredibly quick and easy.

I've created this tutorial from a brand new fresh installation of macOS, and if you already have other software on your computer, you may wish to uninstall conflicting versions before continuing. If you do run into any issues, please do leave a comment and I'll try my best to help.


As with any easy installation, we require a good, robust package manager to do the majority of the hard work for us. In this case, we'll use the wildly popular Homebrew package.

Installation is simple; firstly we need to open Terminal which can be easily found by opening Spotlight via the top right search icon, entering the text "Terminal" and hitting enter on the top hit.

Now we can go ahead and execute the following command to get Homebrew installed.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

The above command may come outdated by the time you're reading this article, if that's the case, please visit https://brew.sh/ for up to date instructions.

The installation will display all new directories and applications installed as part of Homebrew; you can go ahead and hit Enter to accept this and continue the installation.

Terminal will then prompt you for your macOS password; this is a normal part of installations of this kind. You can safely enter your password and hit enter.

Now I'd recommend making yourself a nice warm cup of tea, as this installation can take a few minutes. You can also consider donating to Homebrew as volunteers entirely run it, you can find out more information regarding this on their GitHub: https://github.com/Homebrew/brew#donations.

Installation Successful

Once we see these famous words in the console, we're all done with Homebrew!

We can verify everything is installed by simple running brew help.


As with any package manager Homebrew has a system of locating packages through a variety of repositories. These are called taps within Homebrew; let's go ahead and add one for PHP.

brew tap henkrehorst/php

Now we've successfully added the new tap we can use Homebrew to install PHP 7.2 easily. As you can see by the package name, this is packaged explicitly for usage with Valet+ removing any of the complexities usually required when installing PHP on macOS.

brew install valet-php@7.2

Once again we can verify installation of PHP by executing php -v. You could see the following reported if everything was installed successfully.

Existing PHP Installations

In most cases developers with existing setups will have other PHP versions already installed, for ease of sake I recommend removing these prior to following these instructions as the conflict between PHP versions can cause issues. If you do not see the correct PHP version when running php -v it's most likely another PHP binary which has priority.


We now have a very capable package manager for macOS and we've installed PHP using it, now we need to install PHP's package manager composer.

Thanks to our good friend Homebrew this is as easy as:

brew install composer

Running composer will return the various commands available to be ran by this tool if installation was successful.


Now onto the main event, we've got everything setup we need to install Valet+; as before this is incredibly easy.

Using the composer package manager we can go ahead and install weprovide/valet-plus as a global dependency, this enables us to use the valet command anywhere in the terminal.

composer global require weprovide/valet-plus

Now for probably the most complicated part of this whole tutorial, we need to update our bash profile to include the composer vendors folder. Updating the bash profile allows us to run binary files installed by composer without having to link them manually.

This tutorial was written for a fresh macOS installation we'll assume you're using bash. If you're using an alternative shell you'll need to edit the associated file for that shell; you can find out your shell by running echo $SHELL.

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

The command above adds the required path export to your ~/.bash_profile; it then loads the new contents into your current session.

Now we're able to access the valet binary installed by Composer; we first want to run the fix utility to diagnose and resolve any potential issues we may have in our installation. This command may ask for your password.

valet fix

The fix command has a large amount of output that's not all relevant to a successful installation; I would ignore the majority of the output from this command and only revisit if you have issues with a subsequent step.

The time has come, we're ready to have Valet install the necessary dependencies to create an easy to use development environment.

valet install

Once we see the Valet installed successfully text we're ready to move on.

Setting password for root user failed

If you see this error during your installation, there is no need to panic; this is a standard error with the MySQL installation associated with Valet. Typically this error is due to the MySQL@5.7 version not being linked correctly; we can resolve this by executing the following:

You only need to execute this if your installation failed to set the root user's password.

brew link mysql@5.7 --force
valet install

Verify installation

Valet+ sets up a local proxy to route all *.test requests back to localhost, this means we no longer need to edit the /etc/hosts file for every new website we wish to host.

To verify everything is working lets go ahead and attempt to ping a local test domain.

ping -c1 foobar.test

Creating ~/Sites directory

Now we've got all the tools installed we're ready to go ahead and create a directory to serve all of our Magento installations from. I promote the usage of Sites within your home directory. However, you can change this to your personal preference.

Once we've created the directory, we then go ahead and park the directory. Parking the directory tells valet to serve any subfolder as a web application automatically.

mkdir ~/Sites
cd ~/Sites
valet park

Install Magento 2

We've got two options for our installation composer and git based. Depending on your purpose for this installation you'll want to use the appropriate installation method.

Please note in both installations we use the folder magento2; this is the folder name that Valet will use for the domain name as magento2.test.

Composer based


This uses the composer binary to install all required dependencies for the Magento 2 installation automatically; this is best used for quick installations and merchant sites.

composer create-project --repository=https://repo.magento.com/ magento/project-community-edition magento2

This will require authentication keys for repo.magento.com; these can be retrieved from your Magento.com account.

Git based


The git based installation is best used when making contributions to the core product or when developing on 3rd party extensions.

git clone git@github.com:magento/magento2.git
cd magento2
composer install

Database creation

Now you have all the required files installed on your local system we can go ahead and create a new database for your installation.

valet db create magento2

Now we can use the Magento 2 setup GUI to complete the installation by visiting: http://magento2.test/setup.

Setup GUI

Now we can start moving through the Magento 2 installation.

Step 1: Readiness Check

Valet+ is pre-configured to be fully supported by Magento 2.3; so this step should pass first time.

Step 2: Add a database

We need to tell Magento where to store all information associated with our installation, we earlier created a database called magento2 that we can use for this step.

  • Database Server Host: localhost
  • Database Server Username: root
  • Database Server Password: root
  • Database Name: magento2

Step 3: Web Configuration

Now we configure the store address and admin address. The store address will be completed with the host name automatically, so shouldn't require any further changes. I typically modify the admin address for local development, so it's easier to remember.

Step 4: Customize Your Store

You can set some basic configuration in this customisation step, such as the time zone currency and language. You can also disable specific modules included in your installation under the "Advanced Modules Configurations" section.

Step 5: Create Admin Account

Create a new admin account to enable you to manage your store.

Step 6: Install

The final step, we're ready to complete the Magento installation. Simply click the inviting orange button "Install Now"


Your installation is now completed, you're free to login and configure your Magento instance.

If you run into an issues throughout this tutorial please feel free to post a comment below and I'll try my best to diagnose and resolve your issues.