Skip to main content

​
System Requirements

Before installing Bench, ensure your system meets these requirements:

​
Required

  • Python: 3.10 or higher
  • Operating System: Linux or macOS (Unix-like systems)
  • Git: For cloning repositories
  • Node.js: 18.x or higher (for building assets)
  • Database: MariaDB 10.6+ or PostgreSQL 12+
  • Redis: For caching and background jobs
  • RAM: 4GB minimum, 8GB+ recommended
  • Storage: 10GB+ free space
  • Network: Stable internet connection for downloading apps
Windows Users: Bench does not officially support Windows. Use WSL2 (Windows Subsystem for Linux) or Docker Desktop instead.

​
Installation Methods

Choose the installation method that best fits your needs:

Docker

Recommended for production and quick evaluation

Easy Install Script

Automated setup with minimal configuration

Manual Installation

Full control for development environments
The easiest and most reliable way to run Bench is using Docker. This method works for both development and production.
1

Install Docker

Install Docker and Docker Compose on your system:
# Ubuntu/Debian
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER

# macOS
# Download Docker Desktop from docker.com
Log out and back in after adding your user to the docker group.
2

Clone Frappe Docker Repository

Clone the official Frappe Docker repository:
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
3

Setup Development Environment (Option A)

For development with hot-reload and debugging:
# Copy example environment
cp example.env .env
cp compose.yaml docker-compose.yml

# Start containers
docker-compose up -d

# Create a new site
docker-compose exec backend bench new-site mysite.local --no-mariadb-socket
docker-compose exec backend bench --site mysite.local install-app frappe
4

Setup Production Environment (Option B)

For production deployments with SSL and proper configuration:
# Use the easy-install script (shown in Method 2)
# Or manually configure production compose file
5

Verify Installation

Check that containers are running:
docker-compose ps
Access your site at http://localhost:8080

​
Method 2: Easy Install Script

The easy-install script automates Docker setup and creates a production-ready or development environment.
1

Download the Script

Download and run the easy-install script:
wget https://raw.githubusercontent.com/frappe/bench/develop/easy-install.py
2

Run for Production

Deploy a production environment with ERPNext:
python3 easy-install.py deploy \
  [email protected] \
  --sitename=subdomain.domain.tld \
  --app=erpnext
Parameters:
  • --email: Email for Let’s Encrypt SSL certificate notifications
  • --sitename: Your site’s domain name
  • --app: App(s) to install (can specify multiple times)
  • --version: ERPNext version (defaults to latest stable)
3

Run for Development

Setup a development environment:
python3 easy-install.py develop --project=dev-bench
4

Access Your Installation

After installation completes:
  • Passwords: Saved in $HOME/passwords.txt
  • Compose file: Saved in $HOME/<project-name>-compose.yml
  • Access: http://<your-server-ip> or your configured domain
  • Login: Username is Administrator, password from passwords.txt
The easy-install script automatically installs Docker if not present and handles all configuration.

​
Easy Install Options

python3 easy-install.py deploy [OPTIONS]

Options:
  -n, --project PROJECT        Project name
  -g, --backup-schedule        Backup schedule (default: "@every 6h")
  -i, --image IMAGE           Docker image name
  -q, --no-ssl                Disable HTTPS
  -m, --http-port PORT        HTTP port (default: 80)
  -v, --version VERSION       ERPNext version
  -a, --app APPS              App(s) to install (multiple allowed)
  -s, --sitename SITES        Site name(s) to create
  -e, --email EMAIL           Email for SSL certificate

python3 easy-install.py build [OPTIONS]

Options:
  -j, --apps-json PATH        Path to apps.json with custom apps
  -t, --tag TAGS              Image tag(s) to set
  -p, --push                  Push built image to registry
  -x, --deploy                Deploy after build
  --frappe-path URL           Frappe repository URL
  --frappe-branch BRANCH      Frappe branch to use

​
Method 3: Manual Installation (Development)

For developers who want full control and local installation without Docker.
1

Install System Dependencies

Install required system packages:
# Update package list
sudo apt update

# Install dependencies
sudo apt install -y \
  git python3-dev python3-pip python3-venv \
  redis-server mariadb-server \
  libmysqlclient-dev \
  nodejs npm \
  wkhtmltopdf
2

Install Bench CLI

Install Bench from PyPI:
pip3 install frappe-bench
Verify installation:
bench --version
Add ~/.local/bin to your PATH if the bench command is not found.
3

Configure Database

Setup MariaDB for Frappe:
# Secure MariaDB installation
sudo mysql_secure_installation

# Configure for Frappe (create my.cnf)
sudo nano /etc/mysql/my.cnf
Add these settings:
[mysqld]
character-set-client-handshake = FALSE
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

[mysql]
default-character-set = utf8mb4
Restart MariaDB:
sudo systemctl restart mariadb
4

Start Redis

Ensure Redis is running:
# Ubuntu/Debian
sudo systemctl start redis-server
sudo systemctl enable redis-server

# macOS
brew services start redis
5

Initialize Your First Bench

Create a new bench instance:
bench init frappe-bench --frappe-branch version-15
cd frappe-bench
This creates a directory structure with a Python virtual environment and clones the Frappe framework.
6

Verify Installation

Check that everything is working:
bench --version
bench version
Expected output:
frappe-bench 5.0.0

​
Post-Installation Setup

After installing Bench, configure your environment:

​
Create Your First Site

cd frappe-bench
bench new-site mysite.local
You’ll be prompted for the MySQL root password and administrator password.

​
Install Apps

# Get an app (e.g., ERPNext)
bench get-app erpnext

# Install on your site
bench --site mysite.local install-app erpnext

​
Start Development Server

bench start
Access your site at http://mysite.local:8000
Add 127.0.0.1 mysite.local to your /etc/hosts file for local development.

​
Troubleshooting

The bench executable is not in your PATH. Add it:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Don’t run bench commands with sudo. If you encounter permission issues:
# Fix ownership
sudo chown -R $USER:$USER ~/frappe-bench
Ensure MariaDB is running and accessible:
sudo systemctl status mariadb
mysql -u root -p  # Test connection
If port 8000 is occupied, specify a different port:
bench set-config -g http_port 8001
Check the log file for details:
cat ~/easy-install.log
Common issues:
  • Docker not installed/not running
  • Insufficient disk space
  • Port conflicts (80, 443 already in use)

​
Development vs Production

Development Setup

  • Use manual installation or develop mode
  • bench start for auto-reload
  • Local database and Redis
  • No SSL/NGINX configuration
  • Easy debugging and testing

Production Setup

  • Use Docker or easy-install script
  • NGINX reverse proxy
  • SSL certificates via Let’s Encrypt
  • Supervisor/systemd for process management
  • Automated backups configured

​
Next Steps

Now that Bench is installed:

Quick Start Guide

Create your first bench, site, and install apps

Command Reference

Explore all available Bench commands

Build docs developers (and LLMs) love

Get started for freeTalk to us