Frappe Framework Reference"

DocTypes, controllers, hooks, the ORM, REST API, background jobs, and bench — everything the docs underexplain

🔗Project Structure

 1    # Create a new bench
 2    bench init my-bench --frappe-branch version-15
 3    cd my-bench
 4
 5    # Install an app
 6    bench get-app https://github.com/your/app
 7    bench get-app --branch version-15 erpnext   # specific branch
 8
 9    # Create a new app from scratch
10    bench new-app my_app
11
12    # Create a site
13    bench new-site mysite.localhost --install-app my_app
14
15    # A bench directory looks like this:
16    my-bench/
17    ├── apps/
18    │   ├── frappe/          # core framework
19    │   └── my_app/          # your app
20    │       ├── my_app/
21    │       │   ├── hooks.py             # app-wide configuration
22    │       │   ├── modules.txt          # list of modules
23    │       │   └── my_module/
24    │       │       ├── doctype/
25    │       │       │   └── my_doctype/
26    │       │       │       ├── my_doctype.json      # schema
27    │       │       │       ├── my_doctype.py        # controller
28    │       │       │       └── my_doctype_list.js   # list view config
29    │       │       └── ...
30    ├── sites/
31    │   └── mysite.localhost/
32    │       ├── site_config.json    # DB credentials, site settings
33    │       └── private/files/
34    └── Procfile

🔗Bench CLI

 1    # Development
 2    bench start                        # start all processes (web, worker, scheduler)
 3    bench --site mysite console        # interactive Python REPL with frappe loaded
 4    bench --site mysite mariadb        # open MariaDB shell for the site
 5    bench --site mysite migrate        # run pending migrations (after schema changes)
 6    bench --site mysite clear-cache    # clear redis cache
 7    bench --site mysite clear-website-cache
 8
 9    # App & site management
10    bench --site mysite install-app my_app
11    bench --site mysite uninstall-app my_app
12    bench --site mysite backup
13    bench --site mysite restore path/to/backup.sql.gz
14
15    # Building assets
16    bench build                        # build JS/CSS bundles for all apps
17    bench build --app my_app           # build only your app
18    bench watch                        # watch and rebuild on change (dev)
19
20    # Running scripts
21    bench --site mysite execute my_app.utils.some_function
22    bench --site mysite run-script path/to/script.py
23
24    # Production
25    bench setup production <user>      # configure nginx + supervisor
26    bench restart                      # restart web + workers
27    bench update                       # pull all apps + migrate + build

🔗DocType Schema

A DocType is defined by its .json file. You rarely edit it by hand — use the Desk UI — but understanding the structure is essential.

 1    {
 2      "name": "Project",
 3      "module": "My Module",
 4      "doctype": "DocType",
 5      "is_submittable": 0,
 6      "track_changes": 1,
 7      "fields": [
 8        {
 9          "fieldname": "title",
10          "fieldtype": "Data",
11          "label": "Title",
12          "reqd": 1,
13          "in_list_view": 1
14        },
15        {
16          "fieldname": "status",
17          "fieldtype": "Select",
18          "label": "Status",
19          "options": "Open\nIn Progress\nClosed",
20          "default": "Open"
21        },
22        {
23          "fieldname": "due_date",
24          "fieldtype": "Date",
25          "label": "Due Date"
26        },
27        {
28          "fieldname": "tasks_section",
29          "fieldtype": "Section Break",
30          "label": "Tasks"
31        },
32        {
33          "fieldname": "tasks",
34          "fieldtype": "Table",
35          "label": "Tasks",
36          "options": "Project Task"   
37        }
38      ],
39      "permissions": [
40        { "role": "System Manager", "read": 1, "write": 1, "create": 1, "delete": 1 }
41      ]
42    }

🔗Field Types

🔗Controller (Python)

The controller is a Python class that inherits from Document. Frappe calls lifecycle hooks automatically — you never instantiate or call these yourself.

 1    import frappe
 2    from frappe.model.document import Document
 3
 4    class Project(Document):
 5
 6        # ── Lifecycle hooks (called in this order on save) ──────────────────
 7
 8        def before_insert(self):
 9            # Runs before the document is inserted for the first time.
10            # Good for setting computed defaults.
11            if not self.code:
12                self.code = frappe.generate_hash(length=8)
13
14        def after_insert(self):
15            # Runs after the first INSERT is committed.
16            frappe.publish_realtime("project_created", {"name": self.name})
17
18        def validate(self):
19            # Runs before every save (insert + update).
20            # Raise frappe.ValidationError to abort.
21            if self.due_date and self.due_date < frappe.utils.today():
22                frappe.throw("Due date cannot be in the past", frappe.ValidationError)
23
24        def before_save(self):
25            # Runs after validate, before the DB write.
26            self.last_modified_by = frappe.session.user
27
28        def on_update(self):
29            # Runs after every save is committed.
30            # Safe to trigger side-effects here.
31            self.notify_assignees()
32
33        def before_submit(self):
34            # Only called on submittable DocTypes when status → Submitted.
35            if not self.tasks:
36                frappe.throw("Cannot submit a project with no tasks")
37
38        def on_submit(self):
39            self.db_set("status", "In Progress")  # direct DB update, no re-save
40
41        def before_cancel(self):
42            pass
43
44        def on_cancel(self):
45            self.db_set("status", "Cancelled")
46
47        def on_trash(self):
48            # Runs before the document is deleted.
49            frappe.db.delete("Comment", {"reference_name": self.name})
50
51        # ── Helper methods ────────────────────────────────────────────────
52
53        def notify_assignees(self):
54            for task in self.tasks:
55                if task.assigned_to:
56                    frappe.sendmail(
57                        recipients=[task.assigned_to],
58                        subject=f"Task updated in {self.title}",
59                        message=f"Task {task.title} was updated."
60                    )

Never call self.save() inside validate() or on_update(). It causes infinite recursion. Use self.db_set("field", value) for direct column updates that bypass the lifecycle, or set self.field = value before the current save completes.

🔗The ORM: frappe.db

 1    import frappe
 2
 3    # ── Single value ──────────────────────────────────────────────────────
 4
 5    # get a field value from a document
 6    status = frappe.db.get_value("Project", "PROJ-0001", "status")
 7
 8    # get multiple fields at once (returns a dict)
 9    data = frappe.db.get_value("Project", "PROJ-0001", ["status", "due_date"], as_dict=True)
10
11    # ── Lists ─────────────────────────────────────────────────────────────
12
13    # get all documents matching filters
14    projects = frappe.db.get_all(
15        "Project",
16        filters={"status": "Open"},
17        fields=["name", "title", "due_date"],
18        order_by="due_date asc",
19        limit=50
20    )
21    # returns a list of dicts: [{"name": "PROJ-001", "title": "...", ...}, ...]
22
23    # get_list: same as get_all but respects user permissions
24    projects = frappe.db.get_list("Project", filters={"status": "Open"}, fields=["name", "title"])
25
26    # get_all with OR filters
27    projects = frappe.db.get_all(
28        "Project",
29        filters=[["status", "in", ["Open", "In Progress"]]],
30        fields=["name", "title"]
31    )
32
33    # ── Load a full document ──────────────────────────────────────────────
34
35    doc = frappe.get_doc("Project", "PROJ-0001")
36    doc.title = "Updated Title"
37    doc.save()
38
39    # create a new document
40    doc = frappe.get_doc({
41        "doctype": "Project",
42        "title": "New Project",
43        "status": "Open"
44    })
45    doc.insert()
46    frappe.db.commit()   # always commit after insert/update outside a request context
47
48    # ── Direct DB writes ──────────────────────────────────────────────────
49
50    # update a single field without loading the full document
51    frappe.db.set_value("Project", "PROJ-0001", "status", "Closed")
52
53    # update multiple fields
54    frappe.db.set_value("Project", "PROJ-0001", {
55        "status": "Closed",
56        "due_date": "2025-12-31"
57    })
58
59    # raw SQL (escape your inputs — never use .format() with user input)
60    results = frappe.db.sql("""
61        SELECT name, title FROM `tabProject`
62        WHERE status = %(status)s AND due_date < %(today)s
63    """, {"status": "Open", "today": frappe.utils.today()}, as_dict=True)
64
65    # ── Existence checks ──────────────────────────────────────────────────
66
67    frappe.db.exists("Project", "PROJ-0001")          # returns name or None
68    frappe.db.exists("Project", {"status": "Open"})   # with filters
69    frappe.db.count("Project", {"status": "Open"})    # count matching rows

Table names in raw SQL are always `tab{DocType}`. A DocType named Sales Order lives in `tabSales Order`. Frappe adds the prefix automatically in ORM methods but not in raw frappe.db.sql() — you must write it yourself.

🔗hooks.py

hooks.py is the central wiring file for your app. It controls how your app integrates with Frappe's event system.

 1    # my_app/hooks.py
 2
 3    app_name = "my_app"
 4    app_title = "My App"
 5    app_publisher = "Your Name"
 6    app_description = "What this app does"
 7    app_version = "0.0.1"
 8    app_email = "you@example.com"
 9    app_license = "MIT"
10
11    # ── Document events ───────────────────────────────────────────────────
12    # Hook into any DocType's lifecycle from outside its controller.
13    # Useful for cross-app logic without modifying the original controller.
14
15    doc_events = {
16        "User": {
17            "after_insert": "my_app.handlers.user.on_user_created",
18            "on_update": "my_app.handlers.user.on_user_updated",
19        },
20        "*": {
21            # runs on every DocType
22            "on_submit": "my_app.handlers.audit.log_submission",
23        }
24    }
25
26    # ── Scheduled tasks ───────────────────────────────────────────────────
27
28    scheduler_events = {
29        "all":            ["my_app.tasks.every_5_minutes"],     # ~every 5 min
30        "hourly":         ["my_app.tasks.hourly_sync"],
31        "daily":          ["my_app.tasks.daily_cleanup"],
32        "weekly":         ["my_app.tasks.weekly_report"],
33        "monthly":        ["my_app.tasks.monthly_invoice"],
34        "cron": {
35            "0 9 * * 1-5": ["my_app.tasks.weekday_morning"],    # Mon-Fri 9am
36        }
37    }
38
39    # ── Fixtures ──────────────────────────────────────────────────────────
40    # Records exported with `bench export-fixtures` and imported on migrate.
41
42    fixtures = [
43        "Custom Field",
44        "Property Setter",
45        {"dt": "Role", "filters": [["role_name", "like", "My App%"]]},
46    ]
47
48    # ── Other common hooks ────────────────────────────────────────────────
49
50    # Extend an existing DocType with extra fields (no forking required)
51    # Define the fields in a Custom Field fixture instead.
52
53    # Override a controller method from another app
54    override_doctype_class = {
55        "Sales Invoice": "my_app.overrides.CustomSalesInvoice"
56    }
57
58    # Add JS/CSS to the desk globally
59    app_include_js = ["assets/my_app/js/global.js"]
60    app_include_css = ["assets/my_app/css/global.css"]
61
62    # Add JS to a specific form
63    doctype_js = {
64        "Project": "public/js/project.js"
65    }

🔗REST API

Every DocType automatically gets a REST API. No extra code needed.

 1    # Authentication: get a token
 2    POST /api/method/login
 3    { "usr": "admin@example.com", "pwd": "password" }
 4    # → sets a session cookie, or use token auth below
 5
 6    # Token auth (generate in User > API Access)
 7    Authorization: token api_key:api_secret
 8
 9    # ── CRUD ──────────────────────────────────────────────────────────────
10
11    # List documents
12    GET /api/resource/Project
13    GET /api/resource/Project?filters=[["status","=","Open"]]&fields=["name","title"]&limit=20
14
15    # Get a single document
16    GET /api/resource/Project/PROJ-0001
17
18    # Create
19    POST /api/resource/Project
20    { "title": "New Project", "status": "Open" }
21
22    # Update (partial — only sends changed fields)
23    PUT /api/resource/Project/PROJ-0001
24    { "status": "Closed" }
25
26    # Delete
27    DELETE /api/resource/Project/PROJ-0001

 1    # ── Whitelisted methods ───────────────────────────────────────────────
 2    # Expose a Python function as an API endpoint.
 3
 4    import frappe
 5
 6    @frappe.whitelist()
 7    def get_project_summary(project_name):
 8        # frappe.session.user is available — you know who is calling
 9        doc = frappe.get_doc("Project", project_name)
10        return {
11            "title": doc.title,
12            "task_count": len(doc.tasks),
13            "open_tasks": sum(1 for t in doc.tasks if t.status == "Open")
14        }
15
16    # Call it from JS or curl:
17    # POST /api/method/my_app.api.get_project_summary
18    # { "project_name": "PROJ-0001" }
19
20    @frappe.whitelist(allow_guest=True)
21    def public_endpoint():
22        # allow_guest=True → no login required
23        return {"status": "ok"}

@frappe.whitelist() does not check permissions. Anyone authenticated can call it. Add explicit frappe.has_permission() checks inside the function if the data is sensitive.

🔗Permissions

 1    import frappe
 2
 3    # Check if current user can access a document
 4    frappe.has_permission("Project", doc="PROJ-0001", throw=True)
 5    # throw=True raises PermissionError automatically; throw=False returns bool
 6
 7    # Check a specific permission type
 8    frappe.has_permission("Project", ptype="write", doc="PROJ-0001", throw=True)
 9    # ptype options: read, write, create, delete, submit, cancel, amend
10
11    # Get current user
12    frappe.session.user          # "admin@example.com"
13    frappe.session.user == "Guest"  # True for unauthenticated requests
14
15    # Check role
16    frappe.get_roles(frappe.session.user)           # ["System Manager", "My Role", ...]
17    "System Manager" in frappe.get_roles()          # True/False
18
19    # Programmatic permission bypass (use with care — only in trusted server scripts)
20    frappe.set_user("Administrator")
21    # ... do privileged work ...
22    frappe.set_user(original_user)

🔗Background Jobs

Long-running tasks should never block a web request. Enqueue them.

 1    import frappe
 2
 3    # Enqueue a function to run in a background worker
 4    frappe.enqueue(
 5        "my_app.tasks.send_bulk_email",     # dotted path to function
 6        queue="long",                        # default, short, long
 7        timeout=600,                         # seconds before job is killed
 8        job_name="bulk_email_job",           # optional, for deduplication
 9        # kwargs passed to the function:
10        project_name="PROJ-0001",
11        notify_all=True
12    )
13
14    # The function itself (runs in a worker process)
15    def send_bulk_email(project_name, notify_all=False):
16        doc = frappe.get_doc("Project", project_name)
17        recipients = get_recipients(doc, all=notify_all)
18        for r in recipients:
19            frappe.sendmail(recipients=[r], subject="...", message="...")
20        frappe.db.commit()   # always commit in background jobs
21
22    # Enqueue with deduplication (won't enqueue if job_name already queued)
23    frappe.enqueue(
24        "my_app.tasks.sync",
25        job_name="sync_job",
26        deduplicate=True
27    )

🔗Jinja Templates

Frappe uses Jinja2 for print formats, email templates, and web pages.

 1    # Render a Jinja string from Python
 2    html = frappe.render_template(
 3        "<p>Hello {{ doc.title }}</p>",
 4        {"doc": doc}
 5    )
 6
 7    # Render a template file (relative to app root)
 8    html = frappe.render_template("my_app/templates/email/welcome.html", context)

 1    {# ── Frappe-specific Jinja globals available in all templates ── #}
 2
 3    {# Current user #}
 4    {{ frappe.session.user }}
 5
 6    {# Translate a string #}
 7    {{ _("Save") }}
 8
 9    {# Format a date #}
10    {{ frappe.format_date(doc.due_date) }}
11
12    {# Format a currency value #}
13    {{ frappe.format_value(doc.amount, {"fieldtype": "Currency"}) }}
14
15    {# Link to a document #}
16    <a href="/app/project/{{ doc.name }}">{{ doc.title }}</a>
17
18    {# Conditional #}
19    {% if doc.status == "Open" %}
20      <span class="badge">Open</span>
21    {% endif %}
22
23    {# Loop over child table #}
24    {% for task in doc.tasks %}
25      <li>{{ task.title }} — {{ task.assigned_to }}</li>
26    {% endfor %}

🔗Migrations and Patches

 1    # patches.txt: list of patch modules to run on migrate (one per line, never remove old ones)
 2    # my_app/patches.txt
 3    my_app.patches.v1_0.set_default_status
 4    my_app.patches.v1_1.backfill_project_codes
 5
 6    # A patch file
 7    # my_app/patches/v1_1/backfill_project_codes.py
 8    import frappe
 9
10    def execute():
11        # Runs once per site on `bench migrate`
12        projects = frappe.db.get_all("Project", filters={"code": ""}, fields=["name"])
13        for p in projects:
14            frappe.db.set_value("Project", p.name, "code", frappe.generate_hash(length=8))
15        frappe.db.commit()

Patches run exactly once per site. Frappe tracks executed patches in the tabPatch Log table. If a patch fails halfway, fix it and run bench --site mysite migrate again — it will retry only the failed patch.

🔗Useful frappe Utilities

 1    import frappe
 2    from frappe.utils import (
 3        today, now, nowdate, nowdatetime,
 4        add_days, add_months, date_diff,
 5        flt, cint, cstr,
 6        get_url, get_site_name
 7    )
 8
 9    # Dates
10    today()                          # "2025-06-04"  (string)
11    nowdatetime()                    # "2025-06-04 14:32:00"
12    add_days(today(), 7)             # one week from now
13    date_diff("2025-12-31", today()) # days between two dates
14
15    # Type coercion (safe — never raises)
16    flt("3.14")    # 3.14  (float)
17    cint("42")     # 42    (int), cint(None) → 0
18    cstr(None)     # ""    (str)
19
20    # Messaging (only works inside a web request)
21    frappe.msgprint("Something happened")           # toast on the desk
22    frappe.throw("Validation failed")               # raises ValidationError + shows message
23    frappe.log_error("something broke", title="My App Error")  # writes to Error Log
24
25    # Caching
26    frappe.cache.set_value("my_key", {"data": 1}, expires_in_sec=300)
27    frappe.cache.get_value("my_key")
28
29    # Generating names
30    frappe.generate_hash(length=10)
31    frappe.get_id()                   # UUID