Like Kelly Clarkson, we’re so moving on – and you should too. While the O.G. Magento was a fantastic, giving, understanding, loving option; when something better comes along, you have to do what’s best for you and your business. Do the right thing and install Magento 2. This article will guide you through the initial installation of Magento 2 on macOS or OSX. The article is intended for developers, though it assumes no particular expertise.

Before You Start Your Install

Magento 2 is under rapid development. As such, before installing, you should verify the supported versions of Apache, MySQL, and PHP. At the time of this writing, Magento 2 supports PHP 7.0 and 5.6, but notably does not support PHP 7.1.

Additionally, it is not wise to run arbitrary commands you find on the web. We have taken care to test the commands in this guide, but please be aware that, in general, a single command can brick your computer. So, as opposed to running the commands blindly, we recommend seeking to understand the commands before running them.

Installing the Server Software: MAMP

In production, your Magento site will use the conventional LAMP stack: Linux, Apache, MySQL, PHP. Windows web developers will be familiar with the WAMP suite. For OSX and macOS, we have an analogous suite: MAMP.

  • Download and install MAMP
  • Specify the version of PHP that Magento uses. MAMP>Preferences>PHP, use version 7.0.
  • Create an empty database that Magento will populate.
# default root password is "root"
/Applications/MAMP/Library/bin/mysql -h 127.0.0.1 --port 8889 -u root -p

# in mysql> prompt
SHOW DATABASES;
CREATE DATABASE db_example_project;
SHOW DATABASES;
exit;

Alternatively, you can use a graphical database client like Sequel Pro to create the database. The default MAMP host is 127.0.0.1:8889, username root, password root.

Installing Magento: Using Composer

Like npm and apt, composer is a package manager. The Magento team recommends using Composer to install Magento 2. There are several advantages to using a package manager:

  • Easier upgrades of the core Magento framework for security patches
  • Easier installation of third-party modules
  • Smaller version control repository. With composer, you no longer version the core framework. Instead, you commit two metadata files called composer.json and composer.lock, while the core framework resides in the generated vendor folder.
  • Easy to revert to a clean installation of Magento. Just delete the vendor folder, run composer install, and you’re back to an unmodified core.

In an ironic twist, we will use another package manager to install composer. Homebrew markets itself as “the missing package manager for OSX.” Like the App Store itself, Homebrew simplifies the installation and removal of software on OSX. Once you install Homebrew, simply run:

# install composer
brew install composer

# use MAMP’s php binary instead of the system’s binary.
# You will need to update 7.0.20 to be the current version on PHP, for instance 7.0.22.
echo "export PATH=/Applications/MAMP/bin/php/php7.0.20/bin:$PATH" >> ~/.bashrc

# download magento source code
mkdir ~/src
cd ~/src
composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition example-project 2.1.7
cd example-project

# install magento. modify command with your desired username.
php bin/magento setup:install --base-url="http://127.0.0.1:8888" --base-url-secure="https://127.0.0.1:8888" --db-host="127.0.0.1:8889" --db-name="db_example_project" --db-user="root" --db-password="root" --admin-firstname="John" --admin-lastname="Doe" --admin-email="[email protected]" --admin-user="exampleuser" --admin-password="password2@" --language=en_US --currency=USD --timezone=America/New_York

# Set developer mode. Why this is not the default, I do not know.
# See: http://devdocs.magento.com/guides/v2.1/config-guide/bootstrap/magento-modes.html
php bin/magento deploy:mode:set developer

# update webroot to point to your project
cd /Applications/MAMP

# CAUTION: Tread lightly inside this folder. It contains the brains of your web server.
# move original web root to backup location
mv htdocs htdocs.dist

# instruct apache to use your web root, instead
ln -s ~/src/example-project/ htdocs

# go home
cd

Now, when you visit http://127.0.0.1:8888 in your browser, you should see Magento!

Pro Tips

# Run command line magento commands with a more convenient syntax.
# Optionally add to your ~/.bashrc file to make changes persistent.
alias magento="php bin/magento"

# Disable some caches. This saves you from needing to clear the cache to see any frontend change.
# Unfortunately, you do lose page-load performance. For further optimizations, see: 
# http://devdocs.magento.com/guides/v2.1/extension-dev-guide/build/optimal-dev-environment.html
magento cache:status
magento cache:disable full_page block_html

# Don't suppress runtime errors. Enable them in index.php:
error_reporting(E_ALL);
ini_set('display_errors', 1);

Alternative Installation: Static Files from Zipped Folder

The configuration for the MAMP environment will be identical as described above. The only difference is, instead of using the composer commands to initialize the project, you will download a zipped archive of the source code. You would extract this in that same ~/src directory. For example, the app directory would be present at ~/src/example-project/app. After that, use the same bin/magento commands to install.

Again, this method is more difficult to keep updated. As the framework updates, you would need to manually replace files in the app/code directory. Using composer, you simply modify your composer.json file, run composer update, and the package manager will update the framework in the vendor folder automatically. Though composer is the recommended installation path, Magento still provides the static download.

Alternative Installation: Docker

At the time of this writing, the M2 DevBox Docker container “is currently undergoing an update and is not available for download.” While Docker provides a seamless installation experience, the performance hit on Windows and Mac is too great for a database-intensive application such as Magento. Running Magento under Docker is still a good option, but likely on Linux only, and with a custom Dockerfile.

Resources to install Magento 2 on Docker:
M2 DevBox documentation
M2 DevBox repository on GitHub
Documentation from the Docker organization

Start Developing on Magento 2

If you are going to implement an eCommerce site with Magento 2, you should use the Composer package manager. In a special circumstance, it is still possible to install a static set of files, as was the case with Magento 1. MAMP is a good tool for running the server software locally. Docker is also a possibility, but does not have a supported solution from the Magento team.

For more Magento 2 tips and tricks, check out the Magento DevDocs, the Human Element Twitter feed, and more from the Human Element blog.