How to Install and Uninstall a Custom Frappe App using Bench
Create Install/ Uninstall AppLearn how to create, install, and uninstall custom Frappe applications on your site using the Bench CLI, including commands like new-app, get-app, and install-app.
Managing custom applications is a core part of extending the Frappe Framework. The Bench Command Line Interface (CLI) is the essential tool for handling the entire lifecycle of an app, from its creation or retrieval from a version control system to its installation on a specific Frappe site, and its eventual removal. These commands are fundamental for both development and production environments.
1 // Create a new boilerplate app 2 bench new-app [app_name] 3
4 // Or get an existing app from a git repository 5 bench get-app [app_name] [git_repository_url] 6 // Example: 7 bench get-app fleet_management https://github.com/dalwadani/fleet_management 8
9 // Get a specific version of an app using the --branch flag 10 bench get-app --branch v13 finbyzerp https://github.com/finbyz/finbyzerp.git 11
12 // Switch to the site where you want to install the app 13 bench use [site_name] 14
15 // Install the app on the selected site 16 bench --site [site_name] install-app [app_name] 17 // Example: 18 bench --site site1.local install-app election 19
20 // Uninstall the app from the site (removes database tables and data) 21 bench --site [site_name] uninstall-app [app_name] 22 // Example: 23 bench --site site1.local uninstall-app election 24
25 // (Optional) Remove the app from the list of installed apps if uninstall fails 26 bench remove-from-installed-apps [app_name]
Understanding This Code
What It Does
This collection of Bench commands allows a developer to manage the entire lifecycle of a custom Frappe application, from creation or fetching from a Git repository to installing it on a specific site and subsequently uninstalling or removing it.
When To Use
Use these commands when developing new Frappe applications, deploying third-party apps to your Frappe sites, or cleaning up unused applications from your bench environment.
Prerequisites
- •Frappe Bench installed on your system
- •An active Frappe site
- •Git installed on the server
Key Concepts
Important ideas to understand in this code
Bench CLI
Bench is the command-line tool used to manage a Frappe environment. It handles everything from creating new sites and apps to updating, backing up, and serving your Frappe instance.
Learn moreFrappe App
A Frappe App is a self-contained module that extends the functionality of the Frappe Framework. It can contain DocTypes, scripts, new pages, and business logic. All custom features are typically packaged into apps.
Learn moreFrappe Site
Frappe supports multi-tenancy through 'sites'. Each site has its own database and files, allowing you to run multiple independent instances from a single Frappe bench installation. Commands like 'install-app' are site-specific.
Learn moreStep-by-Step Tutorial
Follow along to understand how this code works
Create or Download the App
First, you need to get the app's source code into your bench's 'apps' directory. You can either create a new boilerplate app using `new-app` or download an existing one from a Git repository using `get-app`.
// Option A: Create a new app
bench new-app my_custom_app
// Option B: Get an app from GitHub
bench get-app erpnext_support https://github.com/frappe/erpnext_supportSelect the Target Site
If you manage multiple sites on your bench, you need to specify which one you are working with. The `bench use` command sets the default site for subsequent commands.
bench use my_site.localInstall the App
Once the app code is in the 'apps' folder and the target site is selected, run the `install-app` command. This will create the necessary database tables (DocTypes) and execute any installation hooks defined in the app.
bench --site my_site.local install-app my_custom_appUninstall the App
To remove an app from a site, use the `uninstall-app` command. This is a destructive operation that will delete all DocTypes and data associated with the app from that site's database.
bench --site my_site.local uninstall-app my_custom_appCommon Issues & Solutions
Troubleshoot problems you might encounter