Skip to main content

​
Overview

This page provides a complete reference of all available bench commands, organized by functional group. Each command includes a brief description and link to detailed documentation where available.
Apart from bench init, all other bench commands should be run from within the bench directory.

​
Initialization & Application Management

Commands for creating and managing bench instances and applications.

​
bench init

Initialize a new bench instance in the specified path. 
bench init [path]
Options:
  • --version, --frappe-branch - Clone a particular branch of frappe
  • --python - Path to Python executable (default: python3)
  • --apps_path - Path to JSON file with apps to install after init
  • --frappe-path - Path to frappe repo
  • --clone-from - Copy repos from path
  • --no-procfile - Do not create a Procfile
  • --no-backups - Do not set up automatic periodic backups
  • --skip-redis-config-generation - Skip redis config generation
  • --skip-assets - Do not build assets
  • --install-app - Install particular app after initialization
  • --dev - Enable developer mode and install development dependencies
See: Getting Started

​
bench drop

Remove a bench instance (only works on empty benches). 
bench drop [path]

​
bench new-app

Create a new Frappe application under the apps folder. 
bench new-app [app-name]
Options:
  • --no-git - Do not initialize git repository (Frappe v14+)

​
bench get-app

Clone an app from the internet or filesystem and set it up in your bench. 
bench get-app [git-url]
Options:
  • --branch - Branch to checkout
  • --overwrite - Overwrite existing app
  • --skip-assets - Do not build assets
  • --soft-link - Create soft link instead of clone
  • --init-bench - Initialize bench if not in one
  • --resolve-deps - Resolve dependencies before installing
  • --cache-key - Cache get-app artifacts (only first 10 chars used)
  • --compress-artifacts - Gzip artifacts for caching
See: Installing Apps

​
bench remove-app

Completely remove app from bench and re-build assets if not installed on any site. 
bench remove-app [app-name]
Aliases: bench rm, bench remove Options:
  • --no-backup - Do not backup app before removing
  • --force - Force remove app

​
bench exclude-app

Exclude app from updating. 
bench exclude-app [app-name]

​
bench include-app

Include app for updating. 
bench include-app [app-name]

​
bench pip

Run pip commands in bench virtual environment. 
bench pip [args...]
Example: 
bench pip install pandas
bench pip list
bench pip help install

​
bench validate-dependencies

Validate that all requirements specified in frappe-dependencies are met. 
bench validate-dependencies

​
Update Commands

Commands for updating bench, apps, and sites.

​
bench update

Performs an update operation on current bench. Without flags, it will backup, pull, setup requirements, build, run patches and restart bench. 
bench update
Options:
  • --pull - Pull updates for all apps in bench
  • --apps - Specify apps to update
  • --patch - Run migrations for all sites
  • --build - Build JS and CSS assets
  • --requirements - Update requirements
  • --restart-supervisor - Restart supervisor processes after update
  • --restart-systemd - Restart systemd units after update
  • --no-backup - Don’t backup sites before update (not recommended)
  • --force - Force major version upgrades
  • --reset - Hard reset git branches to new states
See: Updating

​
bench retry-upgrade

Retry a failed upgrade. 
bench retry-upgrade --version [version]

​
bench switch-to-branch

Switch all apps (or specified apps) to a specified branch. 
bench switch-to-branch [branch] [apps...]
Options:
  • --upgrade - Run bench update after switching

​
bench switch-to-develop

Switch frappe and erpnext to develop branch. 
bench switch-to-develop

​
Development Commands

Commands for development and debugging.

​
bench start

Start Frappe development processes (uses Procfile). 
bench start
Options:
  • --no-dev - Disable development mode
  • --no-prefix - Hide process name from log
  • --concurrency, -c - Number of workers for each process
  • --procfile, -p - Path to custom Procfile
  • --man, -m - Process manager of choice
See: Development Setup

​
bench restart

Restart supervisor processes or systemd units. 
bench restart
Options:
  • --web - Restart only web workers
  • --supervisor - Restart supervisor processes
  • --systemd - Restart systemd units

​
bench src

Print bench source folder path. 
bench src
Usage: 
cd $(bench src)  # Navigate to bench source

​
bench find

Find benches recursively from a location. 
bench find [location]

​
Configuration Commands

Commands for managing bench configuration.

​
bench config

Change bench configuration settings. 
bench config [subcommand]
Subcommands:

​
restart_supervisor_on_update

Enable/disable auto restart of supervisor processes. 
bench config restart_supervisor_on_update [on|off]

​
restart_systemd_on_update

Enable/disable auto restart of systemd units. 
bench config restart_systemd_on_update [on|off]

​
dns_multitenant

Enable/disable bench multitenancy. 
bench config dns_multitenant [on|off]

​
serve_default_site

Configure nginx to serve the default site on port 80. 
bench config serve_default_site [on|off]

​
rebase_on_pull

Rebase repositories on pulling. 
bench config rebase_on_pull [on|off]

​
http_timeout

Set HTTP timeout in seconds. 
bench config http_timeout [seconds]

​
set-common-config

Set values in common_site_config.json. 
bench config set-common-config -c [key] [value]
Example: 
bench config set-common-config -c db_host localhost -c db_port 3306

​
remove-common-config

Remove keys from common_site_config.json. 
bench config remove-common-config [keys...]
See: Configuration

​
bench set-nginx-port

Set NGINX port for a site. 
bench set-nginx-port [site] [port]

​
bench set-ssl-certificate

Set SSL certificate path for a site. 
bench set-ssl-certificate [site] [ssl-certificate-path]

​
bench set-ssl-key

Set SSL certificate private key path for a site. 
bench set-ssl-key [site] [ssl-certificate-key-path]

​
bench set-url-root

Set URL root for a site. 
bench set-url-root [site] [url-root]

​
bench set-mariadb-host

Set MariaDB host for bench. 
bench set-mariadb-host [host]

​
bench set-redis-cache-host

Set Redis cache host for bench. 
bench set-redis-cache-host [host]
Example: 
bench set-redis-cache-host localhost:6379/1

​
bench set-redis-queue-host

Set Redis queue host for bench. 
bench set-redis-queue-host [host]
Example: 
bench set-redis-queue-host localhost:6379/2

​
bench set-redis-socketio-host

Set Redis socketio host for bench. 
bench set-redis-socketio-host [host]
Example: 
bench set-redis-socketio-host localhost:6379/3

​
Setup Commands

Commands for setting up and configuring bench environments.

​
bench setup

Setup command group for enabling Frappe environment. 
bench setup [subcommand]
Subcommands:

​
production

Setup Frappe production environment for specific user. 
bench setup production [user]
Options:
  • --yes - Yes to regeneration of config files
See: Production Setup

​
nginx

Generate configuration files for NGINX. 
bench setup nginx
Options:
  • --logging - Logging type: none, site, or combined (default: combined)
  • --log_format - Specify log format for nginx
  • --yes - Yes to regeneration

​
reload-nginx

Check NGINX config file and reload service. 
bench setup reload-nginx

​
supervisor

Generate configuration for supervisor. 
bench setup supervisor
Options:
  • --user - User to run supervisor as
  • --yes - Yes to regeneration
  • --skip-redis - Skip redis configuration
  • --skip-supervisord - Skip supervisord configuration

​
systemd

Generate configuration for systemd. 
bench setup systemd
Options:
  • --user - User to run services as
  • --yes - Yes to regeneration
  • --stop - Stop bench services
  • --create-symlinks - Create symlinks
  • --delete-symlinks - Delete symlinks

​
redis

Generate configuration for Redis. 
bench setup redis

​
procfile

Generate Procfile for bench start. 
bench setup procfile

​
requirements

Setup Python and Node dependencies. 
bench setup requirements [apps...]
Options:
  • --node - Update only Node packages
  • --python - Update only Python packages
  • --dev - Install optional development dependencies

​
env

Setup Python virtual environment for bench. 
bench setup env
Options:
  • --python - Path to Python executable

​
config

Generate or overwrite sites/common_site_config.json. 
bench setup config

​
sudoers

Add commands to sudoers list for execution without password. 
bench setup sudoers [user]

​
fonts

Add Frappe fonts to system. 
bench setup fonts

​
backups

Add cronjob for bench backups. 
bench setup backups

​
lets-encrypt

Setup Let’s Encrypt SSL for site. 
bench setup lets-encrypt [site]
Options:
  • --custom-domain - Custom domain
  • --custom-server - Custom ACME server URL
  • -n, --non-interactive - Run non-interactively
See: SSL Setup

​
wildcard-ssl

Setup wildcard SSL certificate for multi-tenant bench. 
bench setup wildcard-ssl [domain]
Options:
  • --email - Email for certificate notifications
  • --custom-server - Custom ACME server URL
  • --exclude-base-domain - SSL not applicable for base domain

​
add-domain

Add a custom domain to a particular site. 
bench setup add-domain [domain] --site [site]
Options:
  • --site - Site name
  • --ssl-certificate - Absolute path to SSL certificate
  • --ssl-certificate-key - Absolute path to SSL certificate key

​
remove-domain

Remove custom domain from a site. 
bench setup remove-domain [domain] --site [site]

​
sync-domains

Check if there is a change in domains and update the domains list. 
bench setup sync-domains --site [site] --domain [domain]

​
manager

Setup bench-manager.local site with bench_manager app. 
bench setup manager
Options:
  • --port - Port to run bench manager (default: 23624)
  • --domain - Domain for bench manager
  • --yes - Yes to regeneration

​
firewall

Setup firewall for system. 
bench setup firewall
Options:
  • --ssh_port - SSH port to keep open
  • --force - Force setup without confirmation

​
ssh-port

Set SSH port for system. 
bench setup ssh-port [port]
Options:
  • --force - Force change without confirmation

​
fail2ban

Setup fail2ban intrusion prevention. 
bench setup fail2ban
Options:
  • --maxretry - Number of retries before ban (default: 6)
  • --bantime - Ban duration in seconds (default: 600)
  • --findtime - Time window in seconds (default: 600)

​
role

Install dependencies via ansible roles. 
bench setup role [role]
Options:
  • --admin_emails - Admin email addresses
  • --mysql_root_password - MySQL root password
  • --container - Running in container

​
Install Commands

Commands for installing system dependencies.

​
bench install

Install system dependencies for setting up Frappe environment. 
bench install [subcommand]
Subcommands:

​
prerequisites

Install pre-requisite libraries and tools (bzip2, htop, screen, vim, Redis, etc.). 
bench install prerequisites

​
mariadb

Install and setup MariaDB. 
bench install mariadb
Options:
  • --mysql_root_password - MariaDB root password
  • --version - MariaDB version (default: 10.3)

​
nodejs

Install Node.js. 
bench install nodejs

​
nginx

Install NGINX. 
bench install nginx
Options:
  • --user - Setup sudoers for user

​
supervisor

Install supervisor. 
bench install supervisor
Options:
  • --user - Setup sudoers for user

​
wkhtmltopdf

Install wkhtmltopdf v0.12.3 for Linux. 
bench install wkhtmltopdf

​
psutil

Install psutil via pip. 
bench install psutil

​
fail2ban

Install fail2ban. 
bench install fail2ban
Options:
  • --maxretry - Number of retries
  • --bantime - Ban duration
  • --findtime - Time window

​
Git Commands

Commands for managing git remotes.

​
bench remote-set-url

Set app remote URL. 
bench remote-set-url [git-url]

​
bench remote-reset-url

Reset app remote URL to Frappe official. 
bench remote-reset-url [app]

​
bench remote-urls

Show apps remote URLs. 
bench remote-urls
Output: 
frappe  https://github.com/frappe/frappe.git
erpnext https://github.com/frappe/erpnext.git

​
Utility Commands

Miscellaneous utility commands.

​
bench download-translations

Download latest translations. 
bench download-translations

​
bench renew-lets-encrypt

Renew Let’s Encrypt certificate. 
bench renew-lets-encrypt

​
bench backup-all-sites

Backup all sites in current bench. 
bench backup-all-sites

​
bench disable-production

Disable production environment for the bench. 
bench disable-production

​
bench migrate-env

Migrate virtual environment to desired Python version. 
bench migrate-env [python]
Options:
  • --no-backup - Skip backup of current environment
Example: 
bench migrate-env python3.11

​
bench app-cache

View or remove items from bench get-app cache. 
bench app-cache
Options:
  • --clear - Remove all items
  • --remove-app - Remove items matching app name
  • --remove-key - Remove items matching cache key

​
Global Options

Options available for all bench commands.
  • --version - Show bench version
  • --help - Show help message
  • -v, --verbose - Verbose output
  • --use-feature - Use experimental feature

​
Custom Commands

Bench also loads custom commands from installed Frappe applications. These commands appear alongside built-in commands. See: Custom Commands

Environment Variables

Environment variables used by bench

Configuration Files

Configuration file reference

Custom Commands

Create your own commands

CLI Basics

Learn bench CLI basics

Build docs developers (and LLMs) love

Get started for freeTalk to us