Traditional Installation Guide For Frappe

Note: For production deployments or containerized setups, consider using Docker or Frappe Cloud for easier maintenance.

This guide walks you through manually installing the Frappe development environment on Linux (Ubuntu/Debian) or macOS. This traditional, non-containerized approach offers maximum control but requires a solid understanding of the command line.

⚠️ Compatibility: This guide is intended for Linux (Ubuntu/Debian) and macOS users only. Windows users should install WSL2 or use Codespaces/Frappe Manager.

1. Prerequisites: Installing Dependencies

For Linux (Ubuntu 22.04+)

sudo apt-get update
sudo apt-get install -y git python3-dev python3-pip python3-venv mariadb-server redis-server libmysqlclient-dev wkhtmltopdf

For macOS (using Homebrew)

brew install python@3.11 mariadb redis

All Systems: Node.js, Yarn, and Frappe Bench

Install Node.js (v18), yarn, and Frappe Bench CLI.

Install NVM and Node.js

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

# Load nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install and use Node.js v18
nvm install 18
nvm use 18

Install Yarn

npm install -g yarn

Install Frappe Bench CLI

pip3 install frappe-bench

Verify installation:

bench --version

2. Configure MariaDB

Frappe requires specific configurations in MariaDB.

Run MySQL Secure Installation (Optional but Recommended)

sudo mysql_secure_installation

Edit Configuration File

Edit the config file (Linux):

sudo nano /etc/mysql/my.cnf

Or if you’re on MariaDB (most likely Ubuntu):

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add the following under the [mysqld] section:

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

Restart MariaDB

sudo systemctl restart mariadb

3. Create a New Bench

Create your Frappe Bench workspace.

bench init --frappe-branch version-15 frappe-bench
cd frappe-bench

This creates a frappe-bench folder and sets up the environment.

4. Create a New Site

You can host multiple sites in a bench. Let’s create one.

bench new-site mysite.localhost

You will be prompted to enter the MySQL root password and to set an admin password for the site.

5. Start the Development Server

Start all background services:

bench start

This starts:

• Web server (accessible at port 8000)
• Background workers
• Scheduler

6. Access Your Site

Open your browser and go to:

http://mysite.localhost:8000

Username: Administrator
Password: admin

You will be taken through the setup wizard to choose:

• Country
• Timezone
• Currency

📚 Additional Resources

⚠️ Disclaimer
While this guide offers a simplified installation walkthrough, always refer to the official Frappe website for proper installation, configurations, updates, and troubleshooting.