How to Install Frappe ERPNext on macOS Step-by-Step Guide

Read it Carefully

In modern operating systems like macOS, Python packages are pre-installed for operating system-specific tasks and operations. You can learn more about this by searching PEP 668 or reading PEP 668.

While you could use sudo to access the Python packages already available with the operating system, it is highly discouraged, as it may create issues with OS-specific tasks.

Instead, it's better to create a virtual environment using Python. This virtual environment will help to isolate your installed packages from the system’s Python environment.

Creating a Virtual Environment

To create a virtual environment, navigate to the folder where you want to work, and run:

python3 -m venv env

This will create a virtual environment in the env folder. Next, activate it:

source env/bin/activate

Once activated, you will notice the prefix (env) in your terminal, indicating that the environment is active.

Check Requirements (Ensure the Virtual Environment is Active)

Ensure the following packages are installed on your Mac:

Make sure your brew is updated:

brew update

Install setuptools with pip:

pip install setuptools

Install MariaDB

To install MariaDB:

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

Start the MariaDB service:

brew services start mariadb

To check the status:

brew services list

Set a root password for MariaDB:

sudo mysql -u root

Then run:

ALTER USER 'root'@'localhost' IDENTIFIED BY '123456';
exit;

Secure MariaDB Installation

Run the security script to secure MariaDB:

mariadb-secure-installation

Verify MariaDB Installation

To check if MariaDB was installed successfully:

mysql -V

Access MariaDB

To access the MariaDB CLI:

mysql -u root -p

You may also want to install the MySQL client:

brew install mysql-client

Edit the MariaDB Configuration for Unicode Support

Open the configuration file to set the character encoding:

sudo nano /opt/homebrew/etc/my.cnf

Add the following lines to the file:

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

[mysql]
default-character-set = utf8mb4

Save and exit.

Install Redis

Redis is an in-memory data store used as a cache, database, and message broker. Install Redis with:

brew install redis

Install Node.js 14.x

Node.js is essential for running server-side applications. To install Node.js:

brew install node

For better version management, install Node.js using Volta:

brew install volta
volta install node

Alternatively, you can use nvm for managing Node.js versions. More details can be found here.

Install Yarn

Yarn is a package manager for JavaScript. To install it:

volta install yarn@1

Install wkhtmltopdf

To convert HTML files to PDFs or images, install wkhtmltopdf:

brew install wkhtmltopdf

Install Frappe-Bench

To install Frappe Bench:

sudo -H pip3 install frappe-bench

Once installed, initialize the bench and install Frappe:

bench init frappe-bench --frappe-branch version-15 --verbose

Navigate to the newly created folder:

cd frappe-bench/
bench start

At this step you can access the frappe erpnext on your browser

Create a Site in Frappe Bench

Create a new site:

bench new-site mySite

If you encounter MariaDB-related errors, fix the root login method:

sudo mysql -u root
SELECT user, host, plugin FROM mysql.user WHERE user = 'root';
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '123456';
FLUSH PRIVILEGES;

Install ERPNext

To install the latest version of ERPNext:

bench get-app erpnext --branch version-15
bench --site [siteName] install-app [appName]

For example:

bench --site trySite install-app erpnext

To add the site to hosts:

bench --site trySite add-to-hosts

Now you can access ERPNext using http://trysite:8000/app/.

Final Steps

Finally, run:

bench start

The default username is Administrator, and the password is the one you set earlier.

Switch to unix_socket authentication [Y/n]

Unix Socket Authentication: This method allows the root user to authenticate using the system's user credentials, meaning that you don't need to enter a MariaDB password when logging in as the root user from the terminal. Instead, it uses the operating system's user permissions (e.g., if you are logged in as a system administrator or root on the operating system, you can access MariaDB without needing a password).

Recommendation:

For Development/Local Use: If you're setting up MariaDB on your local machine for development, using unix_socket authentication can be convenient. You can safely choose Y.

For Production: If you're securing a production database, it’s usually better to require a password for root login, so you can choose n to keep using password-based authentication.