Skip to main content

​
What is Bench?

Bench is a command-line utility that helps you install, update, and manage multiple sites for Frappe applications on Unix-like systems for both development and production environments. Built by Frappe Technologies, Bench simplifies the complexity of managing Frappe-based applications like ERPNext, providing a unified interface for common operations from initialization to deployment.

​
Key Features

Bench provides a comprehensive toolkit for managing your Frappe infrastructure:

Bench Initialization

Create and configure new bench instances with isolated Python environments and proper directory structure

Site Management

Create, configure, and manage multiple Frappe sites on a single bench instance

App Management

Install, update, and remove Frappe applications from local or remote repositories

Development Tools

Start development servers with live reload, process monitoring via Procfile, and more

Backup & Restore

Automated periodic backups for all sites with easy restore capabilities

Production Setup

Configure production environments with NGINX, SSL certificates, and process supervision

​
Architecture Overview

Understanding how Bench organizes your Frappe environment: 
frappe-bench/               # Bench root directory
├── apps/                   # All Frappe applications
│   ├── frappe/            # Core Frappe framework
│   └── erpnext/           # Additional apps (e.g., ERPNext)
├── sites/                  # All site instances
│   ├── site1.local/       # Individual site directory
│   │   ├── site_config.json
│   │   └── private/
│   ├── common_site_config.json
│   └── assets/
├── config/                 # Bench configuration
│   ├── nginx.conf
│   ├── supervisor.conf
│   └── redis/
├── env/                    # Python virtual environment
├── logs/                   # Application logs
└── Procfile               # Process definitions

​
How It Works

  1. Virtual Environment: Each bench has an isolated Python environment in the env/ directory
  2. Apps Directory: Frappe applications are cloned and installed in apps/
  3. Sites Directory: Each site has its own database and configuration
  4. Shared Resources: Sites share installed apps but maintain separate data

​
Multi-Tenancy

Bench excels at managing multiple sites (tenants) on a single installation:
  • Each site has its own database and configuration
  • Sites share the same application code for efficiency
  • Install different apps on different sites as needed
  • Isolate backups, migrations, and updates per site
The bench --site flag allows you to run commands for specific sites, making multi-tenant management straightforward.

​
Use Cases

Development Environment
  • Rapid setup with bench start for hot-reload development
  • Easy app creation and testing
  • Multiple test sites for different scenarios
Production Environment
  • Multi-site hosting with production-grade setup
  • Automated backups and monitoring
  • SSL certificate management via Let’s Encrypt
  • Process supervision with Supervisor or systemd
Self-Hosted Deployments
  • Full control over your Frappe infrastructure
  • Containerized deployments with Docker support
  • Flexible scaling and configuration options

​
System Requirements

Python

Python 3.10 or higher required

Platform

Linux or macOS (Unix-like systems)

Database

MariaDB 10.6+ or PostgreSQL 12+

Dependencies

Node.js 18+, Redis, wkhtmltopdf
Bench does not officially support Windows. For Windows development, use WSL2 (Windows Subsystem for Linux) or Docker.

​
Getting Started

Ready to dive in? Here’s your path forward:

Installation

Install Bench using Docker, pip, or the easy-install script

Quick Start

Create your first bench and site in minutes

​
Community & Support

Join the Frappe community for help and discussions:

​
What’s Next?

After understanding what Bench is and how it works:
  1. Install Bench on your system
  2. Follow the Quick Start Guide to create your first site
  3. Explore Commands to unlock Bench’s full potential

Build docs developers (and LLMs) love

Get started for freeTalk to us