Introduction: What Are Modules in Frappe v15?

A Module in Frappe is a logical grouping of DocTypes, pages, reports, scripts, and other assets inside an app. Modules help you organize features and allow users to navigate easily through the Desk sidebar. Frappe loads module information through the module registry, based on metadata defined inside each app.

Modules are not database objects; they are organizational units that group related documents and functionality.

How Modules Work in Frappe (v15)

Modules are registered inside the app’s folder structure, and each module has:

• A module name
• A module definition (Python package)
• A module.txt file storing metadata
• References inside DocTypes, Reports, and Pages

Frappe builds the Desk sidebar and module menu using this metadata.

Where Modules Are Defined in a Frappe App

In any Frappe app, modules reside in:

/your_app/
├── your_app/
│ ├── config/
│ ├── modules.txt
│ ├── module_name/
│ │ ├── __init__.py
│ │ └── module_name.json (optional)

Every module is a Python package, meaning the folder contains an __init__.py file.

Understanding module.txt in Frappe v15

Each module has a module.txt file that declares the module name:

module_name

This is the only value in the file—no JSON, no configuration.
Frappe uses module.txt to:

• Register the module
• Display it on the Desk
• Link DocTypes to the correct module

Modules without a correct module.txt file will not appear in the system registry.

How DocTypes Are Linked to Modules

In the DocType JSON (e.g., doctype_name.json):

{
"module": "Accounts",
"doctype": "DocType",
...
}

The “module” value decides where the DocType appears in Desk.

This ensures navigation grouping inside ERPNext and custom apps.

Module Loading & Registration in Frappe (v15)

During boot and desk load, Frappe:

• Reads installed apps
• Scans modules.txt
• Builds a module registry
• Loads module icons (if present)
• Maps DocTypes, Pages, and Reports to modules

This data builds the left-sidebar menu and determines which user roles see which modules.

Creating a New Module in Frappe v15

Step-by-Step

You can create a module using the bench command:

bench module create <module_name> <app_name>

This generates:

/app_name/app_name/module_name/
├── __init__.py
├── module_name.json (optional, for UI config)
module.txt

You must then:

• Assign your new DocTypes to this module
• Add it to the modules.txt file
• Add module icons (if needed) under /public/icons

Modules & desk.py (Module Configuration)

Inside your app, Frappe uses a Python config file to build module menus:

/your_app/your_app/config/desktop.py

Example:

def get_data():
return [
{
"module_name": "Manufacturing",
"color": "#589494",
"icon": "octicon octicon-gear",
"type": "module",
"label": "Manufacturing"
}
]

This determines:

• Module icon
• Module label
• Module color
• Visibility in Desk

This file controls the visual placement of the module inside the Desk UI.

Best Practices for Modules in Frappe v15

• Keep module structure clean
  Organize DocTypes meaningfully—avoid one module holding everything.
• Use consistent naming
  Follow the app’s naming conventions (e.g., CamelCase for module names).
• Avoid unnecessary modules
  Too many modules clutter the Desk and confuse users.
• Ensure module.txt always matches folder name
  Mismatch causes failed boot or missing modules.
• Use app’s desktop configuration
  Always register modules inside config/desktop.py so users can access them.

Real-World Example: ERPNext Modules

ERPNext organizes functionality into major modules:

Custom apps should follow a similar logical grouping.

Cross-References

Related topics on goerpnext.com:

• DocTypes in Frappe v15
• Desk Sidebar Configuration
• App Structure in Frappe Framework
• Module Icons & Branding in Frappe

Conclusion

Modules in Frappe v15 form the foundation of app organization, navigation, and user experience. They group DocTypes, reports, and pages into meaningful categories, help structure applications, and allow developers to build clear, modular ERP features. Understanding how modules work ensures clean app architecture and a scalable implementation.