Versioning
Adding a pyproject.toml file to your Frappe app is now mandatory. This file defines the supported Frappe Framework versions for your app and helps Frappe Cloud validate compatibility during various operations.
The compatibility check is performed during operations such as:
- bench update
- App installation
- Adding an app to a bench group
Required Configuration
Add a pyproject.toml file in the root directory of your app repository with the following configuration:
[tool.bench.frappe-dependencies]
frappe = ">=16.0.0-dev,<=17.0.0-dev"Configuration Explanation
- tool.bench.frappe-dependencies:
Defines the Frappe Framework compatibility requirements for the app. - frappe:
Specifies the supported Frappe version range using standard version specifiers.
This configuration allows Frappe Cloud to verify whether your app is compatible with the target bench version before performing operations.
Common Errors
1. Missing pyproject.toml
Error Meaning
The application repository does not contain a pyproject.toml file in its root directory.
Resolution
Create a pyproject.toml file in the root directory of your app and add the required Frappe dependency section.
2. Missing [tool.bench.frappe-dependencies] Section
Error Meaning
The pyproject.toml file exists, but the required Frappe dependency configuration is missing or does not follow the expected format.
Resolution
Add the following configuration:
[tool.bench.frappe-dependencies]
frappe = "<version-range>"3. Version Mismatch With Bench
Error Meaning
The app branch declares compatibility with a different Frappe version than the target bench version.
Example scenario:
- Bench group version: 15
- App branch declares compatibility with: develop (v16+)
In this case, the branch will be rejected due to version incompatibility.
Resolution
- Ensure the declared Frappe version range matches the target bench version.
- Switch to an app branch that supports the required Frappe version.
Best Practices
- Keep the Frappe version range updated when releasing new branches.
- Align branch names with the Frappe versions they support.
- Validate app compatibility locally before pushing changes.
- Use semantic version ranges instead of strict version pinning whenever possible.
Summary
The pyproject.toml dependency declaration enables automated compatibility checks across Frappe Cloud infrastructure.
Keeping this configuration accurate helps prevent installation failures, version conflicts, and issues during bench operations.
