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.
- Administrator Access: Some commands require administrative privileges.
- Terminal Application: All the commands provided should be executed in the Terminal.
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.
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 email@example.com firstname.lastname@example.org email@example.com wkhtmltopdf pipx
Follow homebrew’s instructions for adding MariaDB and Redis to your
$PATH. For example (for zsh):
echo 'export PATH="/firstname.lastname@example.org/bin:$PATH"' >> ~/.zshrc echo 'export PATH="/email@example.com/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 /firstname.lastname@example.org/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
[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 email@example.com
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
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
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
After completing the above steps, your ERPNext site should be accessible at:
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
# 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
# install older dependencies brew install firstname.lastname@example.org 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