{"id":7248,"library":"frappe-bench","title":"Frappe Bench","description":"Frappe Bench is a command-line interface (CLI) tool designed to manage multi-tenant deployments of Frappe apps and ERPNext. It handles tasks like initializing new benches, creating sites, installing apps, updating, and configuring services like Nginx and Supervisor. The current version is 5.29.1, with frequent patch and minor releases addressing bug fixes and improvements.","status":"active","version":"5.29.1","language":"en","source_language":"en","source_url":"https://github.com/frappe/bench","tags":["cli","frappe","erpnext","deployment","multi-tenant","devops"],"install":[{"cmd":"pip install frappe-bench","lang":"bash","label":"Install Frappe Bench"}],"dependencies":[{"reason":"Frappe Bench requires Python 3.10 or newer to function correctly.","package":"Python","optional":false}],"imports":[{"note":"Frappe Bench is designed for command-line usage. While it's a Python package, direct programmatic interaction from user scripts is not its primary use case.","symbol":"bench_command","correct":"This is primarily a CLI tool. Direct Python imports are not common for end-users; it's typically invoked via the `bench` command in the terminal."}],"quickstart":{"code":"# 1. Install Frappe Bench (ensure Python >= 3.10 is active)\npip install frappe-bench\n\n# 2. Initialize a new bench directory\nbench init frappe-bench --python `which python3` --frappe-branch main\n\n# 3. Change into the new bench directory\ncd frappe-bench\n\n# 4. Get an app (e.g., Frappe framework itself)\nbench get-app frappe https://github.com/frappe/frappe.git --branch main\n\n# 5. Create a new site\nbench new-site site1.local\n\n# 6. Install the app on the new site\nbench --site site1.local install-app frappe\n\n# 7. Start the bench in development mode (optional)\n# bench start","lang":"bash","description":"This quickstart guides you through installing Frappe Bench, initializing a new bench environment, getting the Frappe application, creating a new site, and installing Frappe on it. Ensure you have Python 3.10 or higher installed and active before starting."},"warnings":[{"fix":"Ensure your environment uses Python 3.10 or a newer version. You can check your Python version with `python3 --version` and switch using tools like `pyenv` if needed.","message":"Frappe Bench now explicitly requires Python 3.10 or newer. Older Python versions will result in installation failures or runtime errors.","severity":"breaking","affected_versions":">=5.25.10"},{"fix":"Frappe Bench version 5.29.1 and later limits `setuptools` to versions below 82 to prevent this. If you encounter this with an older Bench version, try updating Bench or manually ensuring `pip install 'setuptools<82'` in your bench's environment.","message":"Errors like `ModuleNotFoundError: No module named 'pkg_resources'` can occur during site setup or app installation due to conflicts with newer `setuptools` versions. Bench itself attempts to mitigate this.","severity":"gotcha","affected_versions":">=5.29.0"},{"fix":"After updating Bench, regenerate your Nginx configuration using `bench setup nginx`. If you have custom Nginx configurations, remove these directives to avoid Nginx startup errors.","message":"The `ssl_stapling` and `ssl_stapling_verify` directives have been removed from the default Nginx configuration template because Let's Encrypt no longer provides OCSP responses.","severity":"deprecated","affected_versions":">=5.28.0"},{"fix":"For custom apps, ensure the `setup.py` file has a valid `name='your_app_name'` definition that can be parsed by AST, not just a regex match.","message":"App installation may fail if the app's `setup.py` file does not contain a correctly parsed `name` field, leading to an 'App name not found' error.","severity":"gotcha","affected_versions":">=5.27.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `frappe-bench` is updated to at least 5.29.1, which includes a fix to limit `setuptools` version. If the problem persists, manually run `pip install 'setuptools<82'` inside your bench's virtual environment.","cause":"Newer versions of `setuptools` (>=82) have removed `pkg_resources`, which is a dependency for some Frappe components or integrations (like Dropbox).","error":"ModuleNotFoundError: No module named 'pkg_resources'"},{"fix":"Install Python 3.10 or newer on your system. Activate an environment with the correct Python version before running `bench` commands, or specify it explicitly with `bench init --python /path/to/python3.10`.","cause":"The Python version used to run `bench init` or other `bench` commands is older than the required Python 3.10.","error":"Error: Python 3.9.x is not supported by frappe-bench. Please use Python 3.10 or higher."},{"fix":"Run `bench setup nginx` to regenerate the Nginx configuration. If you have custom Nginx settings, manually remove these deprecated directives from your config files.","cause":"Your Nginx configuration still contains `ssl_stapling` or `ssl_stapling_verify` directives, which have been removed from the default Bench Nginx template in recent versions.","error":"nginx: [emerg] unknown directive \"ssl_stapling\" in /etc/nginx/conf.d/your_site.conf"},{"fix":"Verify that your app's `setup.py` file explicitly defines the `name` field, e.g., `setup(name='your_app_name', ...)`.","cause":"Frappe Bench could not correctly parse the app's package name from its `setup.py` file, usually because the `name` field is missing or malformed.","error":"Error: App name not found in setup.py for app 'your_app_name'."}]}