Introduction

Bench is the command-line utility that manages Frappe apps, sites, environments, and production tasks. In Frappe Framework v15, Bench continues to be the backbone for setup, app installation, server management, site migration, and deployment automation.

This guide covers how to install, configure, and use Bench CLI effectively. Whether you’re a developer building ERP apps, a DevOps engineer deploying ERPNext, or a technical consultant setting up clients, this tutorial will equip you with everything you need to manage Frappe projects via Bench.

Core Sections

Overview

Bench simplifies tasks such as:

• Initializing a new Frappe environment
• Managing multiple sites and apps
• Installing apps like ERPNext
• Running local development servers
• Managing background workers and queues
• Generating assets and print formats
• Deploying Frappe in production

Bench is Python-based, extensible, and cross-platform (Linux/macOS).

Installation / Setup

1. Prerequisites

Ensure the following are installed:

• Python 3.10+
• pip
• Node.js 18+
• Yarn
• Redis
• MariaDB 10.6+
• wkhtmltopdf (Qt patched version)
• Git

2. Install Bench CLI

pip install frappe-bench

You can verify the installation:

bench --version

Example output:

5.21.1

3. Create a Bench Instance

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

This initializes a folder (my-bench) with the latest Frappe v15 codebase and necessary structure.

Configuration

Once the Bench instance is created, configure the following:

Add New Site

bench new-site site1.local

Provide:

• MySQL root password
• Administrator email & password

This creates:

• /sites/site1.local
• site_config.json (with DB credentials and app keys)

Install ERPNext (Optional)

bench get-app erpnext --branch version-15
bench --site site1.local install-app erpnext

Start Development Server

bench start

Access at: http://localhost:8000

Functional Use

After setup, Bench allows you to:

• Start the server: bench start
• Restart site services: bench restart
• Backup databases: bench backup
• Run background jobs: bench worker
• Install/uninstall apps: bench install-app, bench uninstall-app
• Setup production: bench setup production
• Migrate database: bench –site site1.local migrate

Example: Running a scheduler

bench --site site1.local execute frappe.enqueue_jobs

Developer Reference / API

Bench wraps common Frappe API tasks into terminal-friendly commands. Key developer tasks include:

• bench update → Pull latest app updates and migrate DB
• bench use → Switch default active site
• bench console → Access Python REPL for debugging

To generate assets:

bench build
bench watch

Bench structure:

my-bench/
├── apps/
├── sites/
│ └── site1.local/
├── Procfile
└── logs/

Practical Use Case

Scenario: A manufacturing company wants to self-host ERPNext.

1. IT admin installs Bench CLI
2. Initializes erp-bench
3. Sets up site erp.sigzen.local
4. Installs ERPNext and HR app
5. Uses bench setup nginx and bench setup production for deployment
6. Automates daily backup with bench backup –with-files

Bench enables rapid provisioning and long-term maintainability.

Advanced Features

• Multisite Management: Host multiple domains with NGINX
• Docker Integration: Bench can generate Docker configs
• Custom Scripts: Hook into pre/post deployment events
• Procfile Customization: Run custom workers or background services

Tips, Best Practices & Pitfalls

Best Practices:

1. Use bench update –reset if you’ve modified core files.
2. Regularly backup sites using bench backup –with-files.
3. Run bench doctor to check for misconfigurations.

Common Pitfalls:

• Mixing global and local Python environments can break Bench.
• Skipping bench build after changing JS/CSS = broken UI.
• Not running bench migrate = schema mismatch.

v15 Notes:

• Improved bench watch for asset building.
• Enhanced support for multiple queues and workers.
• Compatible with Redis 6+ and Node.js 18+.

Visual Suggestion

• Architecture Diagram: Bench → Sites → Apps → DB/Redis/Worker
• Screenshot: Terminal output of bench new-site
• Flowchart: Site creation → App installation → Bench start

Conclusion

Bench CLI is an essential tool for managing Frappe-based apps and infrastructure. With its simplified workflows and automation support, Bench helps developers and ERPNext users quickly spin up, configure, and scale their business applications.