Frappe Bench

Common errors

• ModuleNotFoundError: No module named 'pkg_resources'

  cause Newer versions of `setuptools` (>=82) have removed `pkg_resources`, which is a dependency for some Frappe components or integrations (like Dropbox).
  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.

• Error: Python 3.9.x is not supported by frappe-bench. Please use Python 3.10 or higher.

  cause The Python version used to run `bench init` or other `bench` commands is older than the required Python 3.10.
  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`.

• nginx: [emerg] unknown directive "ssl_stapling" in /etc/nginx/conf.d/your_site.conf

  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.
  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.

• Error: App name not found in setup.py for app '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.
  fix Verify that your app's `setup.py` file explicitly defines the `name` field, e.g., `setup(name='your_app_name', ...)`.

Warnings

• breaking Frappe Bench now explicitly requires Python 3.10 or newer. Older Python versions will result in installation failures or runtime errors.
  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.
• gotcha 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.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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.

Install

• pip install frappe-bench Install Frappe Bench

Imports

• bench_command

  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.

  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.

Quickstart

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.

# 1. Install Frappe Bench (ensure Python >= 3.10 is active)
pip install frappe-bench

# 2. Initialize a new bench directory
bench init frappe-bench --python `which python3` --frappe-branch main

# 3. Change into the new bench directory
cd frappe-bench

# 4. Get an app (e.g., Frappe framework itself)
bench get-app frappe https://github.com/frappe/frappe.git --branch main

# 5. Create a new site
bench new-site site1.local

# 6. Install the app on the new site
bench --site site1.local install-app frappe

# 7. Start the bench in development mode (optional)
# bench start