Frappe Framework Prerequisites
Before you install and build applications with Frappe Framework, you must ensure your system meets certain prerequisites. This guide explains the required software versions, packages, and development environment configuration. This is crucial for ERP consultants, Python developers, and system administrators planning to deploy Frappe-based solutions like ERPNext on production or development servers.
Overview
Frappe Framework relies on a stable combination of open-source technologies. Setting up the correct versions is essential to avoid compatibility issues during installation or while running your ERPNext instance.
The core prerequisites for Frappe, cross-verified from GitHub Frappe, include:
- Python 3.10+
- Node.js 18+
- Yarn 1.22+
- MariaDB 10.6+ or PostgreSQL 13+ (Note: MariaDB is still the default)
- Redis
- wkhtmltopdf with patched Qt
Installation / Setup
Below is a tested and verified sequence to prepare your system for Frappe Framework.
1. Python Environment
Frappe strictly requires Python 3.10+.
# Verify Python version
python3 --version
# Install pip & venv if missing
sudo apt-get install python3-pip python3-venv
2. Node.js and Yarn
Node.js is used for building assets, while Yarn manages JS dependencies.
# Install Node.js 18.x (LTS)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# Install Yarn
npm install -g yarn
# Verify versions
node -v
yarn --version
3. Database Server
Frappe officially supports MariaDB 10.6+.
# Install MariaDB
sudo apt-get install mariadb-server
# Secure MariaDB
sudo mysql_secure_installation
4. Redis Server
Redis handles caching and background jobs.
# Install Redis
sudo apt-get install redis-server
# Enable Redis
sudo systemctl enable redis-server
sudo systemctl start redis-server
5. wkhtmltopdf
Required for generating PDFs (like invoices, quotations) with accurate formatting.
- Version: 0.12.6 with patched Qt for header/footer support.
# Example for Ubuntu
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.bionic_amd64.deb
sudo apt install ./wkhtmltox_0.12.6-1.bionic_amd64.deb
6. Bench CLI
Bench is the command-line tool that orchestrates Frappe sites and apps.
# Install bench globally
pip3 install frappe-bench
Configuration
Once your environment is set up, initialize a new bench directory:
# Initialize bench with Frappe
bench init frappe-bench --frappe-branch version
cd frappe-bench
# Create a new site
bench new-site yoursite.local
# (Optional) Get ERPNext app
bench get-app erpnext --branch version-15
bench --site yoursite.local install-app erpnext
# Start development server
bench start
Tips, Best Practices & Pitfalls
Tips & Best Practices
- Use virtual environments for Python to isolate dependencies.
- Match Node.js LTS exactly to version 18.x to avoid asset build errors.
- Always use the patched version of wkhtmltopdf for header/footer printing.
Pitfalls
- Using unsupported Python or Node versions will break bench start or asset builds.
- Not securing MariaDB can expose your database to threats.
- Missing wkhtmltopdf will fail PDF generation for critical documents.
