Setting up Frappe Bench
System Requirements
- macOS
- Debian / Ubuntu
- Microsoft Windows with WSL
Install Microsoft Windows with WSL
- See How to Install Linux on Windows with WSL
- Install Ubuntu 24.04 LTS in WSL.
Pre-requisites
Python 3.11+ (python 3.12 is inbuilt in 24.04 LTS)
Node.js 18+
Redis 5 (caching and real time 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.6 with patched qt) (for pdf generation)
cron (bench's scheduled jobs: automated certificate renewal, scheduled backups)
NGINX (proxying multitenant sites in production)
Debian / Ubuntu
Update the Linux System
Update linux system software packages using apt:
sudo apt update && \
apt list --upgradable && \
sudo apt dist-upgrade -y && \
sudo apt auto-remove -y
Install Pre-requisites
Install essential softwares and packges to setup Frappe Framework:
sudo apt install software-properties-common build-essential pkg-config curl git
Install Redis
Install Redis using the following command:
sudo apt install redis-server
Check the version of Redis:
redis-server -v
Install MariaDB
Enter the following command to install MariaDB database server:
sudo apt install libmariadb-dev mariadb-server mariadb-client
Note: use default-libmysqlclient-dev insted of libmariadb-dev if there is error occured.
Check MariaDB server version information:
mariadb --version
Run the post-installation security script:
sudo mariadb-secure-installation
Restart MariaDB server
sudo systemctl restart mariadb
Use systemctl to check MariaDB status:
sudo systemctl status mariadb
Install Node.js
Installs nvm (Node Version Manager):
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
Source the shell's rc file:
source ~/.bashrc
Verifies the right nvm version is in the environment:
nvm -v
Download and install Node.js 24:
nvm install 24
Use specific nvm version:
nvm use 24
Update npm (Node.js Package Manager):
npm install -g npm
Verifies the right Node.js and npm:
node -v
npm -v
Install Yarn
Install yarn via npm:
npm install -g yarn
Check installed yarn version:
yarn -v
Install wkhtmltopdf
Install pre-requrisites:
sudo apt install xvfb libfontconfig
Download and install wkhtmltopdf:
curl -L -o wkhtmltox.deb \
https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb && \
sudo sudo dpkg -i wkhtmltox.deb && \
rm wkhtmltox.deb
Test wkhtmltopdf binary:
wkhtmltopdf -V
Install Python
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Source the shell's rc file:
source ~/.bashrc
Install and update Python 3.14:
uv python install 3.14
Install Frappe Framework
Getting Frappe Bench
Install Bench CLI:
uv tool install --python 3.14 frappe-bench
Verify Bench CLI version:
bench --version
Initialize Bench
Syntax:
bench init --frappe-branch [BRANCH] [BENCH_DIR]
Bench initialization with default options will create bench directory with name frappe-bench using default branch (develop):
bench init --frappe-branch
This will create Frappe Bench with version 16 under ~/frappe-bench-v16 directory:
nvm use 24 && \
bench init --frappe-branch version-16 --python python@3.14 frappe-bench-v16
cd frappe-bench-v16 && \
uv python pin 3.14 && \
echo 24 > .nvmrc
This will create Frappe Bench with version 16 under ~/frappe-bench-v15 directory:
nvm install 22 && \
nvm use 22 && \
bench init --frappe-branch version-15 --python python@3.12 frappe-bench-v15 && \
cd frappe-bench-v15 && \
uv python pin 3.12 && \
echo 22 > .nvmrc
Frappe Bench version 15 required Nodejs v22, and Python 3.12.
Errors & Fixes
ZoneInfoNotFoundError: 'No time zone found with key Xxx/Xxxxx'
Go to bench dir:
cd path/to/bench-dir
Install tzdata package with pip:
env/bin/pip install tzdata
Further Steps
See Using Bench CLI