Introduction: What Are Background Jobs in Frappe?
Background jobs in Frappe Framework v15 allow you to execute time-consuming or resource-intensive tasks asynchronously without blocking the user interface or request lifecycle.
They are essential for building scalable ERPNext applications that handle large data processing, integrations, and automation reliably.
Why Use Background Jobs?
Background jobs prevent performance bottlenecks and improve user experience.
- Common reasons include:
- Avoiding request timeouts
- Running long calculations
- Processing bulk data
- Integrating external APIs
- Sending emails or notifications
They ensure responsive UI and system stability.
How Background Jobs Work in Frappe (v15)
Frappe uses a Redis-backed job queue system to manage background execution.
Key components:
- Redis Queue (RQ)
- Worker processes
- Job queues
Jobs are picked up by workers and executed independently of user requests.
What Is frappe.enqueue?
frappe.enqueue is the primary API used to schedule background jobs in Frappe.
It pushes a function into a queue that is processed by background workers.
Basic Example: Enqueue a Background Job
import frappe
def long_running_task():
# time-consuming logic
frappe.db.commit()
frappe.enqueue(
method=long_running_task,
queue="default"
)
This runs the function asynchronously without blocking the request.
Passing Arguments to Background Jobs
You can pass arguments directly to the enqueued method.
def generate_report(report_date):
print(report_date)
frappe.enqueue(
method=generate_report,
queue="default",
report_date="2024-01-01"
)
Arguments must be JSON-serializable.
Available Job Queues in Frappe v15
Frappe provides multiple queues for workload control.
| Queue Name | Purpose |
| short | Quick jobs |
| default | Normal background tasks |
| long | Heavy or long-running jobs |
Choosing the right queue improves performance and reliability.
Delaying Job Execution
Frappe supports delayed job execution using the enqueue_after_commit flag.
frappe.enqueue(
method=long_running_task,
enqueue_after_commit=True
)
This ensures the job runs only after the database transaction is committed.
Running Jobs After Document Events
Background jobs are commonly triggered from DocType events.
def on_submit(doc, method):
frappe.enqueue(
method="my_app.jobs.process_invoice",
docname=doc.name
)
This pattern is widely used in ERPNext workflows.
Monitoring Background Jobs
You can monitor job status from the Desk UI.
Location:
- Desk → Background Jobs
It shows:
- Job status
- Queue
- Execution time
- Errors
This helps with debugging and performance tracking.
Handling Errors in Background Jobs
Always wrap background job logic in proper error handling.
def safe_job():
try:
# job logic
pass
except Exception:
frappe.log_error(frappe.get_traceback(), "Background Job Failed")
Errors are logged and visible in system logs.
Best Practices for Background Jobs
- Keep jobs idempotent
- Commit database changes explicitly
- Avoid UI dependencies
- Use correct queue types
- Log errors and progress
Following these ensures stable production deployments.
Common Use Cases
- Bulk data import/export
- Scheduled reports
- Email notifications
- Ledger posting
- Third-party API sync
Most enterprise ERP operations rely heavily on background jobs.
Troubleshooting Common Issues
Jobs not running?
Ensure Redis is running
Start workers using bench start
Check queue assignment
Jobs stuck in queue?
Verify worker availability
Inspect Redis connection
Unexpected failures?
Review error logs
Add exception handling
Industry Relevance
- Background jobs are critical in:
- Finance and accounting automation
- Manufacturing batch processing
- CRM data synchronization
- Large-scale ERP integrations
They enable scalable and reliable ERP systems.
Target Audience
- Frappe Developers
- ERPNext Consultants
- Backend Engineers
- System Integrators
Technical Prerequisites
- Frappe Framework v15
- Redis configured
- Custom App setup
- Python fundamentals
Official References (Verified)
Documentation:
https://docs.frappe.io/framework/user/en/guides/app-development/running-background-jobs
Frappe GitHub (v15):
