Installation

These steps assume you want to install Bench in developer mode. If you want install in production mode, follow the latest recommended installation methods.

System Requirements

This guide assumes you are using a personal computer, VPS or a bare-metal server. You also need to be on a *nix system, so any Linux Distribution and MacOS is supported. However, we officially support only the following distributions.

  1. MacOS
  2. Debian / Ubuntu

Learn more about the architecture here.

Pre-requisites

  Python 3.7+ (version 13) / Python 3.10+ (develop branch / v14+)
  Node.js 14
  Redis 6                                       (caching and realtime updates)
  MariaDB 10.3.x / Postgres 9.5.x               (to run database driven apps)
  yarn 1.12+                                    (js dependency manager)
  pip 20+                                       (py dependency manager)
  wkhtmltopdf (version 0.12.5 with patched qt)  (for pdf generation)
  cron                                          (bench's scheduled jobs: automated certificate renewal, scheduled backups)
  NGINX                                         (proxying multitenant sites in production)

MacOS

Install Homebrew. It makes it easy to install packages on macOS.

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

Now, you can easily install the required packages by running the following command

brew install python@3.10 git redis mariadb@10.3 node@14
brew install --cask wkhtmltopdf

Now, edit the MariaDB configuration file.

nano /usr/local/etc/my.cnf

And add this configuration

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

[mysql]
default-character-set = utf8mb4

Now, just restart the redis and mariadb services and you are good to go.

brew services restart redis
brew services restart mariadb

Install yarn

Install yarn using npm.

npm install -g yarn

Debian / Ubuntu

Install git, python, and redis

apt install git python-dev python-pip redis-server

Install MariaDB

If you are on version Ubuntu 20.04, then MariaDB is available in default repo and you can directly run the below commands to install it:

apt-get update
apt-get install mariadb-server mariadb-client

During this installation you'll be prompted to set the MySQL root password. If you are not prompted, you'll have to initialize the MySQL server setup yourself. You can do that by running the command:

mysql_secure_installation

Remember: only run it if you're not prompted the password during setup.

It is really important that you remember this password, since it'll be useful later on. You'll also need the MySQL database development files.

Now, edit the MariaDB configuration file.

nano /etc/mysql/my.cnf

And add this configuration

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

[mysql]
default-character-set = utf8mb4

Now, just restart the mysql service and you are good to go.

service mysql restart

Install Node

We recommend installing node using nvm

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

After nvm is installed, you may have to close your terminal and open another one. Now run the following command to install node.

nvm install 14

Verify the installation, by running:

node -v
# output
v14.17.2

Finally, install yarn using npm

npm install -g yarn

Install wkhtmltopdf

apt-get install xvfb libfontconfig wkhtmltopdf

Install Bench CLI

Install bench via pip3

pip3 install frappe-bench

Confirm the bench installation by checking version

bench --version

# output
5.2.1

Create your first bench folder.

cd ~
bench init frappe-bench

After the frappe-bench folder is created, change your directory to it and run this command

bench start

Congratulations, you have installed bench on to your system.