How to Install ERPNext on MacOS

Frappe ERPNext is one of the most popular, free, and open source ERP systems. Frappe ERPNext is a cloud-based integrated enterprise resource planning software that supports manufacturing, distribution, retail, trading, services, education, non-profits, healthcare, and more.

In this guide, we’ll learn how to set up Frappe ERPNext on MacOS, install required dependencies, configure the database configurations, and install the frappe-bench CLI tool to manage multiple sites and apps based on the Frappe Framework.

Installing ERPNext on macOS can be a bit different from other operating systems, as it requires setting up a virtual environment to run ERPNext. The Frappe framework is a full-stack web-based framework based on Python, so it uses the virtual environment to setup isolated environments for multiple Python versions.

Officially, Frappe only supports two OS: MacOS and Linux.

For ERPNext on Ubuntu, read how to install ERPNext on Ubuntu.

A simple and easy way to get started is to install ERPNext using Docker.

Frappe Architecture

Here's a step-by-step guide to help you install ERPNext on macOS:

Requirements:

1. a macOS device
2. pre-installed command line version of Xcode tools

You can install Xcode tools by using this command in your macOS terminal:

xcode-select --install

or using "Software Update" in the system settings.

Step 1 - Install Homebrew

Ensure that you have Homebrew (https://brew.sh/) installed on your macOS. You can check it by using brew -v in your terminal.

If brew is not installed, you can install it in two ways:

1. paste and run the following command in your terminal:

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

2. download the .pkg installer directly from Homebrew's latest Github releases.

This is not a mandatory step but it will make our life easier and other installations much easier.

Step 2 - Install Python, MariaDB, Redis

Next, we will install Python, MariaDB, and Redis using brew that we just installed. Open Terminal and run the following commands one by one:

brew install python@3.9 mariadb@10.3 redis@5.0

You could choose to install specific versions like above or just use plain commands to install the latest updates like below:

brew install python
brew install mariadb
brew install redis

After installation, check their info using:

brew info redis
brew info mariadb

To start mariadb and redis services using:

brew services start mariadb
brew services start redis

Step 3 - Install Node.js and Yarn

ERPNext requires Node.js. Here are 3 ways to install Node.js in macOS:

1. using Homebrew

brew install node

2. using NVM - node version manager

Using the NVM step requires installing NVM first and then using NVM to install Node.js. A lengthier process but very useful in the long run. With NVM, you can install, switch and control multiple versions of Node.js easily using simple nvm commands.

To install nvm in macOS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

To install Node.js using NVM:

nvm install node

Using nvm feels better because it makes Nodejs easier.

3. Download the .pkg installer package for macOS directly from https://nodejs.org/.

After you've successfully installed and verified Node, install yarn using npm:

npm install -g yarn

Verify the yarn installation using:

yarn -v

Step 4 - Install wkhtmltopdf

ERPNext needs wkhtmltopdf to generate PDFs. You can use Homebrew to install wkhtmltopdf by using:

brew install wkhtmltopdf

Or you can also visit the official site at https://wkhtmltopdf.org/downloads.html and select the macOS installer. Once downloaded, double-click on the installer to install it.

If you encounter issues, you can follow another way to install wkhtmltopdf with:

curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-2/wkhtmltox-0.12.6-2.macos-cocoa.pkg -O

installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target ~

Second installer command might require sudo to run but if you want to install without sudo then you need to locate the downloaded package, extract it, find the .pkg file inside, extract its contents once more, and move those binaries to your local bin folder, and export their location into your .zshrc file.

To verify your wkhtmltopdf installation is a success, run the command:

wkhtmltopdf --version

Step 5 - Edit MariaDB Configuration File

Use any text editor of your choice like nano or vim to edit my.cnf in your terminal like:

nano /usr/local/etc/my.cnf

For Apple Silicon M1 or M2 laptops, the file can be found in:

nano /opt/homebrew/etc/my.cnf

Use this configuration and save it in your my.cnf.

[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
bind-address = 127.0.0.1

[mysql]
default-character-set = utf8mb4

Once the config is saved, restart your MariaDB services by using brew:

brew services restart mariadb 

Initialize MariaDB setup using:

mariadb-secure-installation

Step 6 - Install Bench using Pip

Now you're ready to install ERPNext itself. Open Terminal and create a new folder where you want to store the ERPNext files using:

mkdir erpnext
cd erpnext

Next, create a Python virtual environment and activate it:

python3 -m venv env
source env/bin/activate

Now, install Bench using pip3 (pre-installed with Python >3.4) :

pip3 install frappe-bench

Verify the bench installation using:

bench --version

Initialize a new bench instance:

bench init frappe-bench

Create a new Frappe site erpnext.local inside folder frappe-bench using:

cd frappe-bench

bench new-site erpnext.local

Add your new-site to local hosts file so that erpnext.local redirect to 127.0.0.1

bench --site erpnext.dev add-to-hosts

Something like this should be out:

127.0.0.1	erpnext.local
::1	erpnext.local

Step 7 - Configure ERPNext:

Edit the site_config.json file to set up the database settings:

nano sites/erpnext.local/site_config.json

In the editor, add the following lines (you can use any password of your choice):

"db_name": "erpnext",
"db_password": "your_db_password"

Save and close the file (Ctrl + X, then Y, and Enter).

Step 8 - Setup ERPNext using bench:

Now, we will install the Frappe app erpnext in our Frappe site erpnext.local using bench. To do that, first, we download the app from a remote git repo using:

bench get-app erpnext https://github.com/frappe/erpnext

Then, install the downloaded Frappe app erpnext into a specific Frappe site erpnext.local that we created earlier using:

bench --site erpnext.local install-app erpnext

You can read more about the basic usage of the bench here.

Step 9 - Run ERPNext:

Finally, start the development server to run ERPNext:

bench start

You should be able to access the Frappe ERPNext application by opening a web browser and navigating to the following URL:

http://localhost:8000

Congratulations! You have successfully installed ERPNext on macOS.

Login to ERPNext

Use the default username Administrator and the password you set during the installation.

For production setup of ERPNext, you would need to follow a different approach with proper server configuration and security considerations. The installation process might change with newer releases. Always check the ERPNext GitHub repository or ERPNext documentation for the most accurate and up-to-date instructions.

Cloud Service Providers for your ERPNext in Production:

1. DigitalOcean
2. Cloudways

I edit and update this article timely for corrections and improvements. Thank you for reading. Subscribe for more :)