Install Magento 2 Locally on a Mac

---

I recently spent some time creating a local Magento 2 environment on my Macbook Pro.  It was an adventure, and I felt like there were a number of details missing from the tutorials I had followed.

Many of the tutorials were either out of date, vague, or made assumptions on my level of technical knowledge.  So I’d like to share what I learned and walk you through the step-by-step process of creating a local Magento 2 instance on your computer running macOS 10.15.

There are a few things to be aware of before you get started:

• Check out the most current dependencies for Magento 2 before installing anything using this link: https://devdocs.magento.com/guides/v2.3/install-gde/system-requirements-tech.html
• If you are running macOS 10.15, MySQL 5.7 is currently not supported which means when we get to installing MySQL we will install v8.0 and need to make a few minor changes in the MySQL configuration file.

---

Step 1 – Installing Homebrew

To begin we will install homebrew which will be used to install the components necessary to run our localhost. To install homebrew you will open up Terminal and then copy the following command

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

or you can go to their website and follow the instructions there : https://brew.sh/

Once homebrew finishes installing you can now see what services you may already have, you should not have any, using this command

brew services list

 

---

Step 2 – Installing httpd (Apache)

Now that we have homebrew installed we can start installing our Magento dependencies. First, let us begin the installation by entering the following code.

brew install httpd

Once homebrew finishes the installation process you should be able to use our brew services list command to see its status. It should say httpd stopped To start your Apache server you will enter in the following command

brew services start httpd

To test if this worked go to your web browser and enter in localhost:8080 to the URL bar and you should see this:

 

 

---

Step 3 – httpd Configuration

Now that we have successfully launched Apache on your machine we will go forward and begin to edit our Apache configuration settings.

 

Changing Localhost URL

We will be looking for the httpd.conf file located at

/usr/local/etc/httpd

Open httpd.conf with your preferred text editor and look for the following:

listen 8080

To make our URL nicer to use we will want to change this to:

listen 80

This will make it so you only have to type localhost into your URL to pull up your Apache server.

Changing DocumentRoot Directory

Next, you will edit will be the DocumentRoot and directory. By default, it should say:

DocumentRoot “/usr/local/var/www”

I’d recommend you change the path to be in your user directory so it’s easy to access. You can do this by replacing what is above with the location of a directory named www inside your current users home directory:

DocumentRoot "/Users/[your user]/www"
<Directory "/Users/[your user]/www">

If you do this correctly it should look similar to this

Allowing Overrides

The next configuration setting you’ll need navigate to is:

AllowOverride none

Magento 2 Requires that this be set to the following

AllowOverride all

This configuration should now look like this

Enabling the rewrite_module

Now, we need to enable the rewrite_module.  Navigate to:

#LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

We need to uncomment this module so that Magento 2 may use this.  We do this as follows:

LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

Once configured this is what this section should look like.

Setting our User and Group

Finally, you’ll want to specify the local user and their group that you are using for your directory By default, the two variables will look like:

User _www
Group _www

If you are unsure of what your user and user group is, then navigate back to your home directory in the terminal (you can use cd with no arguments to do this) and enter the following

ls -al

This will list everything in your current directory and you should see something like this The important part to look for is in the middle in this case my user is joshuaduda and my user group is staff We now can go ahead and enter this into your configuration document

User [your user]
Group [your user group]

It will look something like this

Testing

We are now done with editing this configuration file for now so you can save/close it before navigating back to your home directory (cd with no arguments) where we will make the directory we specified as the DocumentRoot Directory. Once there, enter the following:

mkdir www

Now, let’s test to see if this worked. Enter in your own path into this command:

Echo “Hello World” > /Users/www/index.html

Now we will want to restart our Apache server so that the changes will take effect

brew services restart httpd

Once this is complete you can go to your web browser and enter in localhost as the URL; this should be the result:

Congratulations you’ve just set up Apache!

 

---

Step 4 – Installing and Setting up MySQL

I want to make a note quickly here as I had mentioned before. Magento 2 currently does not support MySQL 8.0 and MySQL 5.7 does not work with macOS 10.15.

If you are running on macOS 10.14 and don’t plan to update you can install the proper version of MySQL using the following command:

brew install mySQL@5.7

Note that if you are doing this, do not install a newer version of MySQL. Also later in this tutorial there will be a step you can skip (I will point this out).

If you are on macOS 10.15 or installing the latest version of MySQL you will type the following to install MySQL Database

brew install mySQL

Once MySQL installs you can now see that it is a brew service by using the command:

brew services list

You can start MySQL with the command:

brew services start mysql

Preparing MySQL for Magento 2

Once MySQL is running you can type the following in your terminal:

mySQL -u root

For now, your root account has no password, you can change this in the future but for now, we will focus on setting up your database for your magento2 instance.

Now that we are in your MySQL database, let’s start by creating our database by entering the following:

create database magento2

The next step will be to create a user account. This isn’t always necessary but it will avoid some potential installation issues down the road:

CREATE USER 'admin'@'localhost' IDENTIFIED WITH mysql_native_password BY 'admin123';

Feel free to create a different username (‘admin’) or password (‘admin123’), just note that I will be using these values for our installation and that this is only setting an admin account for your MySQL instance, not Magento.

You need to give permissions to this user so that Magento 2 can have access to your MySQL instance and create and update the magento2 database. Enter the following to grant these permissions:

GRANT ALL PRIVILEGES ON *.* to 'admin'@'localhost';

Once you have done this you can use the following to flush the privileges so that your database is up to date:

flush privileges;

That is everything we need to set up in MySQL so go ahead and log out:

exit;

This will log you out of MySQL and take you back to your main terminal.  MySQL should be ready for Magento 2 installation

 

---

Step 5 – Installing PHP 7.3

Notice that I specified the version here. Currently, Magento 2 does not support PHP 7.4 so you need to be careful when installing PHP that you do not install an incompatible version.

Install PHP 7.3 by entering the following command:

brew install php@7.3

this may take a little while and feel like it is frozen but be patient as homebrew runs parts of the installation in the background

Now once homebrew finishes the installation, you can check your brew services list – you should see php@7.3 stopped.   To start PHP on your localhost type:

brew services start php@7.3

Configuring httpd for php@7.3 module

If you try to run PHP on Apache as we are right now, PHP would not run. That is why we need to go back to our httpd configuration file found in:

/usr/local/etc/httpd

In httpd.conf we need to navigate back to the rewrite_module and add the correct PHP module below it by entering the following:

LoadModule php7_module /usr/local/opt/php@7.3/lib/httpd/modules/libphp7.so

It should now look like this:

There is also one more section that we need to modify: navigate to DirectoryIndex. Specify index.php in the directory index by adding to:

 DirectoryIndex index.html

So it matches:

DirectoryIndex index.php index.html

The result should be:

Once this is done go ahead and save this configuration file.

 

Testing to see if PHP is running on Apache

One last step in setting up PHP and that is testing to see if it all works. We need to navigate back to the directory you created previously (/www) and create a new PHP document in here and call it index.php Inside index.php copy the following code

Now we need to restart are Apache server once more to read the new configurations

brew services restart httpd

and now if you go to your web browser and enter “localhost”, you should see this:

If this is being displayed and you see Version 7.3.* you should be all set to move on to the next step!

 

---

Step 6 – Installing Composer and Magento 2

We want to install Composer our package builder which will allow us to download the Magento 2 environment onto your machine.

Installing Composer

We need to make sure we are in our local Apache directory:

/Users/[your user]/www

Once you are here, copy the following lines of commands and paste them into your terminal

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

You can also use the current installation method found at: https://getcomposer.org/download/

Once that completes you should see a file name composer.phar We can now install composer by typing

php composer.phar install

Installing Magento 2 Using Composer

Now that composer is installed we can go ahead and install Magento 2 to our Apache server. I will give you the command for both Magento Open Source and Magento Commerce, although I realize you have to have the proper authentication keys from Magento.

If you do not know how to get your magento 2 authentication keys follow the tutorial at this link: https://devdocs.magento.com/guides/v2.3/install-gde/prereq/connect-auth.html

The Magento Open Source command is

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

Or for Magento Commerce

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

You can also find these commands at: https://devdocs.magento.com/guides/v2.3/install-gde/composer.html

If these commands don’t work, an easy workaround is to try replacing “composer” for the following

php composer.phar ...

When you begin the installation you will be prompted to enter in a username and a password Your username will be your public key and your password will be your private key

note that for security reasons the terminal will not display any values for password

Once this is complete we are almost done! Here is the part where we do final setup and fix compatibility issues.

 

---

Step 7 – Permissions and MySQL 8.0 Compatibility Fix

Permissions

To start we’ll ensure that we allow Magento commands to execute. To do this you need to navigate to your magento2 folder inside of your local Apache directory:

cd ~/www/magento2

Once there, we need to enter a simple command that will allow Magento 2’s commands to run:

chmod a+x bin/magento

Errors

If you tried to run your Magento 2 installation process now, you would fall into a couple of different errors.  Below are the methods I used to fix these issues – hopefully, they’ll be useful to you!

Increasing PHP memory_limit

First, we’ll give Magento the correct amount of ram so that there are no memory errors on installation. To do this we will need to access the php.ini file. To find that, type:

php --ini

You are looking for the loaded configuration file:

Mine is located at /usr/local/etc/php/7.3/php.ini.  I used a text editor to find a line containing:

memory_limit

The default value will not be enough for Magento 2 to set up so we will need to change this to either 4G –  or if you end up still having memory issues -1 which will give Magento 2 as much memory as it needs.

memory_limit = 4G

This is what it should look like

You can now save and close this document

Fixing MySQL 8.0 Compatibility Errors

If you are on macOS 10.15 or using MySQL 8.0 you will need to make the following changes inside Magento 2 to work properly on your machine

First, we need to navigate to the file Mysql.php found in:

~/magento2/vendor/magento/framework/DB/Adapter/Pdo

Open up Mysql.php with your preferred editor and find:

case 'smallint':

Directly below this line, you need to add:

case 'smallint unsigned':

You also will need to do a similar thing after:

case 'int':

Directly below adding:

case 'int unsigned':

This section of the file should now look like this:

 

Once you’ve completed these steps, you may save and close this document then navigate back to the magento2 directory inside of your Local Apache directory.

 

---

Step 8 – Launching the Site

Let’s begin by restarting all of our brew services so that we can be sure our changes have all been applied:

brew services restart httpd
brew services restart mysql
brew services restart php@7.3

There are currently two ways of going about installation.  Magento recommends using the command-line since the web setup wizard will be deprecated once Magento 2.4 launches.

Note that if you run into any issues, Magento will list the error it has run into. A great thing to do if that happens is to try copying and pasting the error code into your web browser and see what comes up. The good thing about Magento is there is a large community around it using many different machines meaning you can find people similar issues who have gotten very helpful feedback.

The Command-line Way

Again make sure you are inside of your magento2 directory and then you will enter in the following:

bin/magento setup:install --base-url=http://localhost/magento2/ --db-host=localhost --db-name=magento2 --db-user=admin --db-password=admin123 --admin-firstname=Magento --admin-lastname=Admin --admin-email=user@example.com --admin-user=admin --admin-password=admin123 --language=en_US --currency=USD --timezone=America/Chicago --use-rewrites=1

This should work if you’ve set everything up exactly as I have and if you’d like to learn more about each of these options you can find that at https://devdocs.magento.com/guides/v2.3/install-gde/install/cli/install-cli-install.html#instgde-install-cli-magento

If this runs correctly you will see this:

Once this completes it will display your admin URL which will allow you access the backend. You are all set now! To see your website enter the following into your web browser

localhost/magento2

You should see your Magento 2 frontend now! To access the backend you will add your unique admin URL to the end of your URL, for example, my admin URL is

localhost/magento2/admin_4cwub1

You will be directed to the admin login screen now.

The username and password will be what you set it to during installation – in our case username will be admin and password will be admin123

The Setup Wizard Method

To access this method we actually need to go to our internet browser and type in the following localhost/magento2/setup First, you’ll agree to the terms and agreement for Magento.

Next Magento will double check your compatibility.

If you run into issues here you will have to do some troubleshooting although Magento gives you good feedback to work off of.

Next, we will set up our database.  All we need to enter is the database host, which will be localhost, the MySQL username, and password, which will be admin and admin123, and lastly the name of the database we created, which will be magento2.

 

 

Now we will set up our store’s web address, you can change this to be anything you’d like although that will require some more steps of configuration that I will not cover and can sometimes cause issues.

For the admin address, you can change this, but it’s recommended you keep this randomized for security reasons.

Now, we’ll set up our store default timezone, currency, and language:

 

 

Next, we will make our admin account for our website. In this case, I just used a generic username and email but feel free to make any of this whatever you’d like:

Now that You’ve completed all of the other steps in the Magento setup wizard process you can proceed and click install.

Again remember, if you run into any issues the error codes provided and the Magento community are a very great troubleshooting resource

Now that you’ve finished up you can type the URL into your browser and your website will load!

localhost/magento2

To access the backend remember to copy the admin URL that Magento 2 has given you at the conclusion of the installation process.  I’ll use the URL provided by the setup wizard:

localhost/magento2/admin_4cwub1

 

---

Conclusion

I hope that this guide is useful and will make your efforts to set up Magento 2 on your Mac a bit easier. If you get stuck, there are a number of resources and troubleshooting tips available within the Magento 2 Community and Magento Support. Or comment below and we’ll give it a shot! If you are unsure of what to do next now that you have Magento 2 installed here’s some suggestions to get started.