Introduction

Bench is a CLI tool to manage Frappe Deployments. It provides an easy interface to help you setup and manage multiple sites and apps based on Frappe Framework.

However, the term bench may mean different things depending on the context. We use the term "bench" to refer to the CLI tool and the directory interchangeably. This may get confusing a lot of times.

"Did you update the bench?"

"Yes, migrations for the latest version were smoother this time around."

"What?! I told you to update the CLI tool!"

"Let's hope our clients like Version 13"

To avoid these type of situations, we will refer to "Bench" as the bench directory and "Bench CLI" to refer to the CLI tool.

To install the bench CLI and setup a Frappe environment, please follow the installation instructions.

You may be surprised to know that a lot of the bench commands are provided by the Frappe Framework, not by the Bench CLI directly. In general, these are the commands which work on a specific site (can use the --site parameter). Even commands like bench update only provide thin wrappers around Frappe Framework commands such as backup and migrate, along with some other essential bench and system-level operations.

---

Using the bench CLI

➜ bench
Usage: bench [OPTIONS] COMMAND [ARGS]...

 Bench manager for Frappe

Options:
 --version
 --help Show this message and exit.

Commands:
 backup
 update
 config
 ...

Similarly, all available flags and options can be checked for commands individually by executing them with the --help flag. The init command for instance:

➜ bench init --help
Usage: bench init [OPTIONS] PATH

 Initialize a new bench instance in the specified path

Options:
 --python TEXT # Path to Python Executable.
 --ignore-exist # Ignore if Bench instance exists.
 --apps_path  # TEXT path to json files with apps to install after init

---

Basic Usage

Create a new bench

The init command will create a bench directory with the Frappe framework installed. It will be setup for periodic backups.

bench init frappe-bench && cd frappe-bench

Add a site

Frappe apps are run by Frappe sites and you will have to create at least one site. The new-site command allows you to do that.

bench new-site site1.local

Add apps

The get-app command gets remote Frappe apps from a remote git repository and installs them.

bench get-app erpnext https://github.com/frappe/erpnext

Install apps

To install an app on your new site, use the bench install-app command.

bench --site site1.local install-app erpnext

Start bench

To start using the bench, use the bench start command.

bench start

To login to Frappe / ERPNext, open your browser and go to [your-external-ip]:8000, probably localhost:8000. The default username is Administrator and password is what you set when you created the new site.

Update bench

Update all apps and sites from your bench directory. This operation performs backups, sets up requirements, builds assets, runs migrations and restarts your process manager.

bench update

Update Bench config

To add or update an existing config key:

bench config set-common-config -c enable_frappe_logger true

To remove an existing config key:

bench config remove-common-config enable_frappe_logger

---

Bench Commands

The Bench CLI uses the module frappe.utils.bench_manager to get the framework's as well as any other application's commands present on the current bench directory.

To see all available commands:

bench --help

To see options for a specific command:

bench [command] --help

---

General Commands

These commands belong directly to the bench group and can be invoked as bench [command].

bench init [bench-name] Initialize a new bench instance in the specified path. Sets up an apps/ folder for Frappe apps, sites/ for site data, config/ for redis/NGINX/supervisor configs, and env/ for Python dependencies.

bench init frappe-bench && cd frappe-bench

Option	Description
--python TEXT	Path to Python executable
--ignore-exist	Ignore if bench instance already exists
--apps_path TEXT	Path to JSON file with apps to install after init
--frappe-path TEXT	Path to frappe repo
--frappe-branch TEXT	Clone a particular branch of frappe
--clone-from TEXT	Copy repos from path
--clone-without-update	Copy repos from path without updating
--skip-redis-config-generation	Skip redis config generation
--verbose	Verbose output during install

bench update If executed in a bench directory, without any flags will backup, pull, setup requirements, build, run patches and restart bench. Using specific flags will only do certain tasks instead of all.

bench update

Option	Description
--pull	Pull changes in all apps
--patch	Run migrations for all sites
--build	Build JS and CSS artifacts
--bench	Update bench itself
--requirements	Update requirements
--restart-supervisor	Restart supervisor after update
--no-backup	Skip backup before update
--reset	Ignore local changes and update

bench restart Restart web, supervisor, systemd process units. Used in production setup.

bench start Start Frappe development processes using the Procfile.

bench src Print bench source folder path. Can be used to navigate to the bench repo:

cd $(bench src)

bench find [path] Find benches recursively from location or specified path.

bench migrate-env [python-version] Migrate virtual environment to the desired Python version. Regenerates the env folder with the specified Python version.

bench retry-upgrade Retry a failed upgrade.

bench renew-lets-encrypt Renew Let's Encrypt certificate for site SSL.

bench disable-production Disables production environment for the bench.

bench version Show version of all apps.

Option	Description
-f / --format	Show branch and last commit info (v13+)

bench pip Use the current bench's pip to manage Python packages.

bench pip help [command]
bench pip [command] -h

---

App Commands

bench get-app [repo-url] Download an app from the internet or filesystem and set it up in your bench. Clones the git repo of the Frappe project and installs it in the bench environment.

bench get-app erpnext https://github.com/frappe/erpnext

Option	Description
--branch [branch-name]	Fetch a specific branch

bench new-app [app-name] Create a new Frappe application under the apps/ folder.

bench remove-app [app-name] Completely remove the specified Frappe app from the current bench and re-build assets if not installed on any site.

bench exclude-app [app-name] Exclude app from updating during a bench update.

bench include-app [app-name] Include app for updating. All Frappe applications are included by default when installed.

bench switch-to-branch [branch] [apps...] Switch all apps to specified branch, or specify apps separated by space.

bench switch-to-develop Switch Frappe and ERPNext to develop branch.

bench remote-set-url Set app remote url.

bench remote-reset-url Reset app remote url to frappe official.

bench remote-urls Show apps remote url.

---

Site Commands

Site-specific commands use the --site flag with the site name, or all to run the operation on all sites.

bench --site [site-name] [command]

To avoid typing --site every time, export the environment variable:

export FRAPPE_SITE=mysite.localhost

bench new-site [site-name] Create a new site on your bench. By default, all sites created will have only the Frappe Framework installed.

bench new-site site1.local

Option	Description
--db-name	Database name
--db-host	Custom database host URL for remote connection
--db-port	Custom database listening port
--mariadb-root-username	Root username for MariaDB
--mariadb-root-password	Root password for MariaDB
--admin-password	Administrator password for new site
--install-app	Install app after installation
--force	Force restore if site/database already exists
--source_sql	Initiate database with a SQL file
--verbose	Verbose output

bench --site [site] install-app [app-name] Install a Frappe app on your site. The app must be present on the bench prior to this.

bench --site site1.local install-app erpnext

bench --site [site] uninstall-app [app-name] Uninstall an app installed on site. This is a destructive action — all app-related data is removed from the site. A backup is taken before uninstalling.

Note: From Version 13, even apps not installed on the bench can be uninstalled from the site.

bench --site [site] list-apps List all Frappe applications installed on the specified site. Multi-site support (using all) was added in Version 13.

bench --site [site] migrate Run patches, sync schema and rebuild files, translations and indexes.

Option	Description
--rebuild-website TEXT	Rebuild webpages after migration

bench --site [site] backup Backup site data. Saved to ~/frappe-bench/sites/{site}/private/backups/. Also deletes backups older than 24 hours by default.

Option	Description
--with-files	Backup site with files

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

bench --site [site] restore [path/to/database/file] Restore an existing site to a previous state. Accepts .sql.gz or .sql files.

Option	Description
--with-private-files	Restore site with private files (path to tar file)
--with-public-files	Restore site with public files (path to tar file)

bench drop-site [site] Drops the database and moves the site directory from ./sites to ./archived_sites.

Option	Description
--root-login	DB root login
--root-password	DB root password

bench --site [site] reinstall Re-install all installed applications from the specified site. Completely resets the site.

bench --site [site] set-admin-password [password] Reset the Administrator password for a site.

bench --site [site] set-config [key] [value] Add or update a key-value pair in the site's config file.

bench --site [site] show-config Display the applied configuration for a site — a combination of common_site_config.json and site_config.json. Supports tabular and JSON formats.

bench --site [site] browse Open the site URL directly in your default browser.

bench --site site.local browse
bench --site site.local browse --user Administrator

Note: Login as any user only works when developer_mode is set to 1. Login as Administrator works regardless.

bench use [site] Set default site for bench.

bench --site [site] mariadb / bench --site [site] postgres Start the interactive DB console for the site. bench --site [site] db-console is an alias for both.

bench --site [site] --force reinstall Reinstall with fresh database.

Caution: Will wipe out old database.

Site Operations & Debugging

Command	Description
add-system-manager	Add a new system manager to a site
add-user	Add a new user with specific roles to a site
add-to-hosts	Add the specified site to the hosts file
build-search-index	Build search index for websites
disable-user	Disable user on site
publish-realtime	Publish realtime event from bench
reload-doc	Reload schema for a DocType and refresh the specified document
reload-doctype	Reload schema for a particular DocType
remove-from-installed-apps	Remove the app from the site's installed apps global value
run-patch	Run a particular patch via the Frappe Patch Handler
execute	Run one-off Python statements
migrate-to	Migrate your local site to a Frappe Hosting Provider's service
ngrok	Create a temporary URL to share your local site. Primarily for third party service development
set-password	Set the password for any user
set-admin-password	Set the password for the Administrator user
set-last-active-for-user	Set user's last active date to current datetime
start-recording	Start the Frappe Recorder for the specified sites
stop-recording	Terminate the Frappe Recorder for the specified sites
destroy-all-sessions	Clear sessions of all users (logs them out)

---

Database Maintenance

bench --site [site] transform-database Manage engine and row format settings for site database tables.

bench --site {site} transform-database --tables {tables}

bench trim-tables Remove columns from database tables for DocFields that no longer exist. Benefits include smaller backups, reduced backup time, optimized queries, and a clean database.

bench trim-database Remove ghost tables left behind by deleted DocTypes or migrations.

---

Scheduler & Background Jobs

Command	Description
bench enable-scheduler	Enable scheduler for specified sites
bench disable-scheduler	Disable scheduler for specified sites
bench scheduler	Change scheduler state: pause, resume, disable, enable
bench doctor	Get diagnostic info about scheduler status and active workers
bench show-pending-jobs	Get diagnostic info about background jobs
bench purge-jobs	Purge pending periodic tasks. Without --event, purges everything for the site
bench ready-for-migration	Check if a site is ready for migration by checking for pending background jobs
bench set-maintenance-mode	Set maintenance mode value in config for specified sites
bench trigger-scheduler-event	Trigger a specific scheduler event for specified sites
bench schedule	Start the scheduler process for your bench
bench worker	Start a worker process on your bench

---

Development

bench console Open an IPython console for the site.

Option	Description
--autoreload	Reload changes to code automatically

bench execute [method] Execute a method inside any app.

bench execute frappe.utils.scheduler.enqueue_scheduler_events

bench serve Start a development web server.

Option	Description
--port	Start the web server on a different port (default: 8000)
--profile	Add profiler middleware that prints which backend methods get called, how often, and how long they take
--proxy	Run behind a proxy e.g. ngrok / localtunnel
--noreload	Disable automatic restarting when files change
--nothreading	Disable handling of concurrent requests using threads
--with-coverage	Measure code coverage and create coverage.xml in sites/. Also activates --noreload and --nothreading

bench run-tests Run tests.

Option	Description
--app	App name
--doctype	DocType to run tests for
--test	Specific test
--module	Run a particular module that has tests
--profile	Runs a Python profiler on the test

bench run-ui-tests Run Cypress UI tests.

bench run-parallel-tests Run Python tests parallelly on CI.

bench jupyter Start a Jupyter Notebook server.

bench make-app Create a boilerplate Frappe application.

bench build Build assets for the Frappe applications installed on bench.

bench watch Watch and concatenate JS and CSS files as and when they change.

bench request Make a request as Administrator with arguments to a path.

bench reset-perms Reset permissions for all DocTypes to their default settings.

---

Data & Import/Export

Command	Description
bench data-import	Import documents in bulk from CSV/XLSX
bench export-csv	Export data import template with data for a DocType
bench export-doc	Export a single document to CSV
bench export-json	Export doclist as JSON to the given path. Use - as name for Singles
bench export-fixtures	Export records from a site to your Frappe app as JSON files
bench import-csv	Import from CSV using data import
bench import-doc	Import (insert/update) doclist. If the argument is a directory, all .json files are imported
bench bulk-rename	Rename multiple records via a CSV file

bench data-import options:

Option	Description
--file	File name
--doctype	The DocType
--type	Insert or Update

---

Config Commands

Usage: bench config [command]

Command	Description
set-common-config -c [key] [value]	Set value in common config
remove-common-config [key]	Remove specific keys from current bench's common config
update_bench_on_update [on/off]	Enable/disable bench updates on running bench update
restart_supervisor_on_update [on/off]	Enable/disable auto restart of supervisor processes
restart_systemd_on_update [on/off]	Enable/disable auto restart of systemd units
dns_multitenant [on/off]	Enable/disable bench multitenancy
serve_default_site [on/off]	Configure nginx to serve the default site on port 80
http_timeout	Set HTTP timeout

bench config set-common-config -c enable_frappe_logger true
bench config remove-common-config enable_frappe_logger

---

Setup Commands

Usage: bench setup [command]

Command	Description
env	Setup Python's virtual environment for your bench
config	Generate or overwrite sites/common_site_config.json
redis	Generate configuration for Redis
nginx	Generate configuration files for NGINX
supervisor	Generate configuration for supervisor
systemd	Generate configuration for systemd
procfile	Generate Procfile for bench start
production [user]	Setup a Frappe production environment. Installs ansible, NGINX, supervisor, fail2ban and generates respective config files
requirements	Setup Python and Node dependencies
socketio	Setup node dependencies for socketio server
backups	Add cronjob for bench backups
sudoers	Add commands to sudoers list for allowing bench commands without root password
fonts	Add Frappe fonts to system
firewall	Setup firewall for system
ssh-port	Set SSH port for system
reload-nginx	Check NGINX config file and reload service
fail2ban	Setup fail2ban, an intrusion prevention software framework
lets-encrypt	Setup Let's Encrypt SSL for site
wildcard-ssl	Setup wildcard SSL certificate for multi-tenant bench
add-domain	Add a custom domain to a particular site
remove-domain	Remove a custom domain from a site
sync-domains	Check if there is a change in domains. If yes, updates the domains list
role	Install dependencies via ansible roles
manager	Setup bench-manager.local site with the Bench Manager app

bench setup requirements options:

Option	Description
--node	Update only Node packages
--python	Update only Python packages
--dev	Update only Python development dependencies

---

Install Commands

Usage: bench install [command]

Command	Description
prerequisites	Install pre-requisite libraries and essential tools
nodejs	Install Node.js
nginx	Install NGINX
mariadb	Install and setup MariaDB
supervisor	Install supervisor
fail2ban	Install fail2ban
wkhtmltopdf	Install wkhtmltopdf v0.12.3 for Linux
psutil	Install psutil via pip
virtualbox	Install VirtualBox
packer	Install Oracle VirtualBox and Packer

---

Translation Commands

There are two ways to manage translations. Until v15, translations are based on CSV files. Starting from v16, Frappe manages translations using the .po file format from GNU Gettext.

CSV-based (up to v15)

Command	Description
build-message-files	Build message files for translation
get-untranslated	Get untranslated strings for language
update-translations	Update translations for set language between files
new-language	Create a [lang].csv file for the given application
migrate-translations	Migrate target-app-specific translations from source-app to target-app

Gettext / PO-based (v16+)

Command	Description
generate-pot-file	Generate a POT file containing all translatable strings of your app
compile-po-to-mo	Compile PO files to MO files for production
update-po-files	Sync language PO files with POT file — adds new strings, removes outdated ones
create-po-file	Create a new (untranslated) PO file for a new language
migrate-csv-to-po	Migrate app translations from CSV files to PO files

---

Release Commands

Command	Description
bench release	Create a release of a Frappe application
bench prepare-beta-release	Prepare major beta release from develop branch