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 (and a bit easier).

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:

Note (April 2024): this has been integrated into the default Procfile and is now obsolete.

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
cd version-14

# install an app with the specific branch
bench get-app erpnext --branch version-14-hotfix
16 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

On my latest try, I encountered an error when starting honcho: ModuleNotFoundError: No module named pkg_resources

I was able to resolve this by installing setuptools in the same python virtual environment as honcho:

/Users/$USER/.local/pipx/venvs/hocho/bin/python3 -m pip install -U setuptools

Also, for newly created benches, the section 4.1 Silence errors caused by RQ on Mac is no longer required, since it has been incorporated into the bench’s Procfile.

@rmeyer

I am using the macbook os sonoma v14.5, if I restart the system means the mariadb service goes off and try to start it using the command “brew services start mariadb” means getting an error like this Bootstrap failed: 5: Input/output error Try re-running the command as root for richer errors. Error: Failure while executing; /bin/launchctl bootstrap gui/502 /Users/albertmontolio/Library/LaunchAgents/homebrew.mxcl.mariadb.plist exited with 5. so how to solve this?

I don’t get this error

Did you specify the MariaDB version in your start command?

brew services start mariadb@10.6

@rmeyer
Bootstrap failed: 5: Input/output error this is what I also get

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

/opt/homebrew/opt/mariadb@10.6/bin/mysqladmin: connect to server at ‘localhost’ failed
error: ‘Can’t connect to local server through socket ‘/tmp/mysql.sock’ (2)’
Check that mariadbd is running and that the socket: ‘/tmp/mysql.sock’ exists!
➜ ~