--- title: "Overview" space: "Framework draft" url: "https://docs.frappe.io/framework-copy/bench/overview" updated: "2026-02-19" --- ## 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](/framework/v14/user/en/installation). 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 ```zsh ➜ 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: ```zsh ➜ 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. ```sh 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. ```sh bench new-site site1.local ``` ### Add apps The `get-app` command gets remote Frappe apps from a remote git repository and installs them. ```sh 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. ```sh bench --site site1.local install-app erpnext ``` ### Start bench To start using the bench, use the `bench start` command. ```sh 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. ```sh bench update ``` ### Update Bench config To add or update an existing config key: ```sh bench config set-common-config -c enable_frappe_logger true ``` To remove an existing config key: ```sh 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: ```sh bench --help ``` To see options for a specific command: ```sh 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. ```sh 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. ```sh 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: ```sh 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. ```sh 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. ```sh 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. ```sh bench --site [site-name] [command] ``` To avoid typing `--site` every time, export the environment variable: ```sh 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. ```sh 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. ```sh 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. ```sh 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. ```sh 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. ```sh 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 | ```sh 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 |