Single DocType in Frappe Framework (Version 15)

A Complete, SEO-, AEO-, and GEO-Optimized Technical Guide

1. Introduction to Single DocType

A Single DocType in Frappe Framework is a unique document type that stores configuration or master information in a single record instead of a table of multiple records. Unlike standard DocTypes, it does not create a database table. Instead, field values are stored in the tabSingles table as key–value pairs.

Single DocTypes are used for system-wide configuration settings such as:

• System Settings
• Website Settings
• Global Defaults
• Notification Settings
• Print Settings

These doctypes help centralize configuration, making Frappe and ERPNext easier to manage.

2. What Makes a DocType “Single”?

It contains exactly one document

Users cannot create multiple entries.

Data is stored in tabSingles

Instead of a dedicated table (like tabCustomer).

Used only for configuration, not transactions

It should never represent a transactional or list-based object (e.g., Sales Invoice).

Automatically renders a form view without listing page

Because there is only one record.

3. How Single DocType Works Internally (Frappe v15)

Database Storage Structure

Each field in the Single DocType is stored as an independent row.

Backend Logic Source (v15)

Frappe GitHub (Version 15):
https://github.com/frappe/frappe/tree/version-15/frappe/model/document.py

The system treats the Single DocType differently:

• No INSERT into tab<doctype>
• Reads and writes are handled through frappe.db.get_single_value() and frappe.db.set_single_value() APIs.

4. Configuration & Setup

How to Create a Single DocType in Frappe v15

1. Go to:
   Desk → Developer → DocType
2. Click New
3. Set:
   • Is Single → ✔ Enabled
4. Add fields normally (Data, Select, Check, etc.)
   
5. Save the DocType

Once saved:

• You can open it directly (e.g., /app/[module]/[doctype])
• There will be no list view, only a form view.

5. Code Examples (Python & JS)

5.1 Python: Getting a Value from Single DocType

import frappe
expiry = frappe.db.get_single_value("System Settings", "session_expiry")
print(expiry)

5.2 Python: Setting a Value

import frappe
frappe.db.set_single_value("System Settings", "session_expiry", "7200")

5.3 Get Entire Document as Object

doc = frappe.get_single("Website Settings")
print(doc.home_page)

5.4 Client Script Example (v15)

frappe.ui.form.on('Website Settings', {
refresh(frm) {
console.log(frm.doc.website_theme);
}
});

6. When Should You Use Single DocType?

(Decision Guide)

Use It When:

• You need global configuration (e.g., currency settings, time zone)
• Only one record is expected
• Fields define system behavior, not business records
• You want a lightweight metadata store

Avoid When:

• You need multiple entries (customers, items, employees)
• You require permissions per document
• Workflow or approvals are required
• You need to log submission or cancellation

7. Real-World Examples of Single DocTypes

These are essential for ERPNext and Frappe installations.

8. Best Practices (Frappe v15 Recommendations)

DO:

•  Keep Single DocTypes small and simple
• Use them only for configuration
• Use API functions instead of direct DB queries
• Document each field’s purpose clearly

DO NOT:

• Store large data (JSON, big text blocks)
• Use for transaction logging or analytics
• Use child tables (NOT supported in Single DocTypes)
• Use for user-specific settings (use User Settings DocType instead)

9. Troubleshooting Common Issues

1. Fields not saving?

✔ Check if is_single is enabled in the DocType.
✔ Check for validation errors in the browser console.

2. Getting Null Values in Python?

Ensure field name matches exactly (case-sensitive).

3. Value resets after reload?

Check if any hook or client script is overwriting defaults.

4. How to reset a Single DocType?

Use:

bench --site [sitename] reload-doc module doctype single_doctype_name

Conclusion

The Single DocType is an essential component of the Frappe Framework (Version 15), designed for storing configuration data efficiently without generating database tables. It simplifies system-wide settings, reduces overhead, and ensures centralized control of ERPNext and Frappe applications.