Installing Frappe/ERPNext (develop branch) on MacOS (Apple Silicon) for Development

This guide will walk you through the process of setting up Frappe/ERPNext for a development environment on Apple Silicon. Follow these steps carefully to ensure a smooth setup.

Prerequisites:

  1. Administrator Access: Some commands require administrative privileges.
  2. Terminal Application: All the commands provided should be executed in the Terminal.

1. Setting up the Environment as Administrator

For the following commands, you’ll need a user with administrative privileges.

1.1 Install Homebrew:
Homebrew is a package manager for MacOS, which allows you to install software packages easily.

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

1.2 Allow homebrew for the non-admin user (optional)

If you want to run your bench as a non-admin user, it will need access to everything inside /opt/homebrew/. To get the exact commands, you can run brew doctor as the non-admin user, then execute them as the admin user.

2. Setting up the User Environment

The following commands can (mostly) be run as a normal, non-privileged user. If you want to setup ERPNext for the admin user, that’s fine as well.

2.0 (Optional) Install Oh-My-Zsh:
This enhances your terminal experience, making it more user-friendly.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

2.1 Add homebre to your path:

If you’re using zsh, add Homebrew to your path to easily access its commands. If you are using a different shell, these commands will be different.

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc

2.2 Install Essential Packages:
We’ll need Python, MariaDB, Redis, wkhtmltopdf, and pipx for our setup.

brew install python@3.11 mariadb@10.6 redis@6.2 wkhtmltopdf pipx

Follow homebrew’s instructions for adding MariaDB and Redis to your $PATH. For example (for zsh):

echo 'export PATH="/opt/homebrew/opt/mariadb@10.6/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/opt/redis@6.2/bin:$PATH"' >> ~/.zshrc

2.3 Set MariaDB Root Password:
To secure your MariaDB installation, set a root password. Replace $NEW_PASSWORD with your desired password.

sudo /opt/homebrew/opt/mariadb@10.6/bin/mysqladmin -u root password $NEW_PASSWORD

Note: this command needs to be run as the admin user.

2.4 Configure MariaDB:
Ensure MariaDB uses the appropriate character sets.
Add the following configurations into /opt/homebrew/etc/my.cnf.d/frappe.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

2.5 Restart MariaDB:
To apply the changes, restart MariaDB.

brew services restart mariadb@10.6

2.6 Install NVM (Node Version Manager):
NVM allows you to manage multiple Node.js versions.

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

2.7 Install Essential Tools:
Next, we’ll install the bench CLI, process manager honcho, NodeJS v18, and the package manager yarn.

pipx install frappe-bench
pipx install honcho
nvm install 18
nvm use 18
npm i -g yarn

In order for the bench and honcho commands to become available, you might need to run pipx ensurepath and restart you terminal.

2.8 Setup Frappe/ERPNext:
Now, we’ll initialize a new bench and set up ERPNext. This can be done in any directory you like, for example ~/Code/Bench.

cd ~/Code/Bench # optional (create these directories beforehand)

# The `--no-backups` flag is used to avoid configuring crontab, which needs higher privileges.
bench init --python python3.11 --no-backups develop
cd develop/
bench get-app erpnext
bench new-site develop.localhost --install-app erpnext
bench start

3. Accessing Your Site:

After completing the above steps, your ERPNext site should be accessible at:

4. Special Tricks

4.1 Silence errors caused by RQ on Mac:
You’ll notice that you’ll frequently get “Python ended unexpectedly” error messages. To avoid this, add the following line to your shell configuration (for example ~/.zshrc) (source):

# Avoid "python ended unexpectedly" bug, caused by RQ
export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

4.2 Always use the right node version:
When you’re using multiple versions of node, you’ll have to run nvm use [version] before you can use commands like bench build. To avoid this, you can add node to your virtualenv:

nvm use 18 # select the desired node version
ln -s $(which node) env/bin/node # link the specific node version in you virtualenv
ln -s $(which yarn) env/bin/yarn # link the specific yarn version in you virtualenv

Now whenever you activate your virtual environment (source env/bin/activate), you’ll be using not only the correct python but also the correct node and yarn.

4.3 Initialize benches with older versions:

For example, let’s get a bench named “version-14”, running frappe’s version-14-hotfix branch:

# install older dependencies
brew install python@3.10
nvm install 16
nvm use 16
npm i -g yarn

# initialize a bench with the specific branch
bench init --python python3.10 --no-backups --frappe-branch version-14-hotfix version-14
14 Likes

Thanks for sharing

I have been searching for this guide for an extended period, attempting multiple times, yet encountering difficulties specifically with MariaDB.

@rmeyer any update?

I added “1.6 Allow homebrew for the non-admin user (optional)”. That (followed by reinstalling mariadb and my frappe sites) did the trick.

One last problem remains: MariaDB doesn’t automatically start on login. We need to run brew services start mariadb@10.6 once after logging into the notebook.

The GitHub CLI is also very useful for contributing to frappe (apps).

Install:

brew install gh

Enable auto completion in zsh (optional, there are similar commands for other shells):

gh completion -s zsh > /opt/homebrew/share/zsh-completions/_gh

Try mariadb 10.8. First remove all other versions of mariadb.

brew install mariadb@10.8

I have used Macports successfully. Only issue is that any major OS upgrade will require reinstallation

At a second try, I had trouble with MariaDB as well. I think one issue was that I installed MariaDB as admin user, then tried to use it as non-admin, resulting in wrong default-permissions. I adjusted the order/user for the commands above so that it should work better now.

I want an environment where I can start all the services when I need to develop something. So that my performance and battery doesn’t suffer when I don’t do development.

How can I do that with this install?

The only thing running in the background is MariaDB. I think it doesn’t drain your battery, it just occupies some of your RAM. You can start/stop it with brew services start mariadb@10.6 / brew services stop mariadb@10.6.

All the other services, you start with bench start and stop with control + c.

It should also be possible to not install MariaDB as a service in the first place. Instead, you always start it explicitly by adding an entry to your Procfile. But you’ll need to figure this out yourself.

1 Like

Thank you @rmeyer