Introduction
As a Django application grows, you may need certain actions to happen automatically when something occurs in your application.
For example:
- Create a profile when a user is created.
- Update information after a model is saved.
- Delete related files when an object is removed.
- Send a notification after a specific event.
- Update another model when data changes.
One way to handle these events is with Django Signals.
Django Signals provide a way for different parts of an application to communicate when a particular event occurs.
They can be extremely useful when used correctly, but they can also make an application difficult to understand if they are overused.
In this guide, we’ll explain Django Signals, how they work, the most commonly used signals, practical examples, and when you should—and shouldn’t—use them.
What Are Django Signals?
Django Signals allow certain parts of a Django application to receive notifications when specific events occur.
The basic idea is:
Something happens → Signal is triggered → Receiver performs an action
For example:
User is created → Signal fires → Profile is created
Or:
Blog post is saved → Signal fires → Related action is performed
Signals allow applications to respond to events without putting all the related logic directly into the code that triggered the event.
How Do Django Signals Work?
Django Signals use two main concepts:
Signal
The signal represents an event that has occurred.
Receiver
The receiver is the function that responds to that event.
A simplified flow looks like this:
Event occurs
↓
Signal is sent
↓
Receiver is notified
↓
Receiver performs an action
For example:
User created
↓
post_save signal
↓
Profile receiver
↓
Create user profile
This is the core concept behind Django Signals.
Why Use Django Signals?
Signals can be useful when an action should happen automatically as a result of another event.
For example, imagine your application has a User model and Profile model.
Whenever a new user is created, you want a profile to be created automatically.
Instead of requiring every part of your application to remember to create the profile, a signal can handle the operation whenever the appropriate event occurs.
This can reduce duplicated code in some situations.
Common Django Signal Types
Django provides several built-in signals.
Some of the most commonly used ones include:
pre_savepost_savepre_deletepost_deletem2m_changedrequest_startedrequest_finished
For most beginners, the most important signals to understand are the model-related signals.
What Is post_save?
post_save is triggered after a Django model instance has been saved.
For example:
Product saved → post_save → Receiver executes
It is commonly used for actions that should happen after a record has been created or updated.
Typical use cases include:
- Creating related records
- Sending notifications
- Updating related information
- Triggering secondary operations
Example: Creating a Profile After User Creation
A common Django Signals example is automatically creating a profile for a user.
The basic idea is:
New User Created
↓
post_save
↓
Check if user was newly created
↓
Create Profile
The signal can determine whether the User object was newly created or simply updated.
This distinction is useful because you usually don’t want to create a new profile every time the user record is updated.
What Is pre_save?
pre_save is triggered before a model instance is saved.
This makes it useful when you need to perform an action before Django writes the object to the database.
For example, it might be used to:
- Modify a field before saving
- Generate certain values
- Normalize data
- Perform a custom check
The important difference is:
pre_save → Before saving
post_save → After saving
pre_save vs post_save
| Signal | When It Runs | Common Use |
|---|---|---|
| pre_save | Before model is saved | Modify or prepare data |
| post_save | After model is saved | Trigger follow-up actions |
Choosing between them depends on whether the operation needs to happen before or after the database save.
What Is pre_delete?
pre_delete is triggered before a model instance is deleted.
It can be useful when you need to perform an action before deletion.
For example, you might need to:
- Record information about the object
- Clean up related resources
- Perform a custom check
- Prepare data before deletion
What Is post_delete?
post_delete is triggered after a model instance has been deleted.
It can be useful for cleanup tasks.
For example, imagine a model contains a reference to an uploaded file.
After deleting the model record, you may also need to remove the associated file from storage.
A post_delete signal can be used as part of such a cleanup workflow.
What Is m2m_changed?
m2m_changed is used when a Many-to-Many relationship changes.
For example, imagine a Course model and Student model.
A course can have many students, and a student can enroll in many courses.
If students are added to or removed from a course, the m2m_changed signal can notify your application about the relationship change.
This signal can be useful when you need to react to changes in many-to-many relationships.
Django Signals and Model Events
Most signal-based workflows are related to model events.
A simplified model lifecycle might look like:
Create Object
↓
pre_save
↓
Database Save
↓
post_save
For deletion:
Delete Object
↓
pre_delete
↓
Database Delete
↓
post_delete
Understanding this lifecycle makes it easier to choose the appropriate signal.
The created Parameter
When using post_save, Django provides information about whether the object was newly created.
This is particularly useful for workflows such as profile creation.
For example:
created = True
means the object was newly created.
While:
created = False
generally means the object already existed and was updated.
This distinction helps prevent unwanted repeated operations.
Django Signals Example: Welcome Notification
Imagine that your application should send a welcome notification when a new customer registers.
The workflow could be:
Customer Created
↓
post_save Signal
↓
Check created
↓
Send Welcome Notification
This can keep the notification-triggering behavior separate from the code responsible for creating the customer.
However, for important external operations such as email delivery, using a background task system can often be a better architecture than performing the operation directly inside a signal.
Django Signals Example: Creating Related Data
Suppose your application has:
User
and:
UserProfile
Whenever a new User is created, the application should create a corresponding UserProfile.
A signal can automate this workflow.
The benefit is that the profile creation logic doesn’t need to be repeated in every part of the application that creates users.
Django Signals Example: Cleaning Up Files
Imagine you have a Document model containing an uploaded PDF.
When the document record is deleted, the actual file might still exist in storage.
A deletion signal can be used to trigger cleanup.
The flow becomes:
Document Deleted
↓
post_delete
↓
Delete Associated File
This can help prevent unused files from accumulating.
However, file cleanup should be designed carefully when using external storage such as Amazon S3 or other object storage systems.
Django Signals Example: Updating Related Information
Suppose your application stores a summary or derived value based on another model.
When the source model changes, a signal could trigger an update.
For example:
Order Updated → Signal → Update Related Summary
This can be useful for certain tightly coupled data relationships.
However, if the business logic becomes complex, a dedicated service layer or explicit workflow may be easier to understand.
Custom Django Signals
Django also allows developers to create custom signals.
Custom signals can represent application-specific events that aren’t covered by Django’s built-in signals.
For example:
- Payment completed
- Booking confirmed
- Order shipped
- Course completed
- Subscription activated
- Report generated
A custom event could follow this pattern:
Booking Confirmed
↓
Custom Signal
↓
Receivers
↓
Notifications / Logging / Other Actions
This can be useful when multiple independent parts of your application need to react to the same event.
Built-in Signals vs Custom Signals
Built-in Signals
Django provides these automatically for certain events.
Examples:
post_savepre_savepost_deletepre_deletem2m_changed
Custom Signals
You define these for your own application events.
Examples:
payment_completedbooking_confirmedsubscription_activated
Both approaches follow the same basic idea:
Event → Signal → Receiver
Where Should Django Signals Be Defined?
A common approach is to create a signals.py file inside the Django application.
For example:
myapp/
├── models.py
├── views.py
├── signals.py
├── apps.py
└── ...
The signal receivers can be placed in signals.py.
This helps keep signal-related code separate from models and Views.
Registering Signals
Defining a signal receiver isn’t always enough.
Django needs to load the signal code so that the receiver is registered when the application starts.
A common approach is to import the signal handlers from the application’s configuration.
The important idea is:
Signal code must be loaded when Django starts.
Otherwise, you may create a receiver that never actually executes because Django never registered it.
Why Signal Registration Matters
A common beginner problem is:
“I created a signal, but it isn’t working.”
One possible reason is that the signal receiver was never imported.
For example:
signals.py exists
↓
But Django never loads it
↓
Receiver isn't registered
↓
Signal doesn't execute
Always make sure your signal configuration is properly loaded when the application starts.
Django Signals and Transactions
Signals can interact with database transactions in ways that developers need to understand.
Suppose a signal triggers another database operation.
If the surrounding operation is part of a transaction, you need to consider when related actions should actually happen.
For example, sending an email immediately after a model save may not always be ideal if the transaction later fails.
This is one reason Django provides transaction-related tools such as transaction.on_commit().
For important workflows, external actions can often be triggered only after the database transaction successfully commits.
Django Signals and Celery
Signals are sometimes used together with Celery for background tasks.
For example:
Order Created
↓
post_save Signal
↓
Celery Task
↓
Send Email
The signal detects the event, while Celery handles the potentially slow operation in the background.
This can be useful for:
- Emails
- Notifications
- Image processing
- Report generation
- External API calls
- Other time-consuming tasks
The important principle is to avoid making user requests wait unnecessarily for expensive operations.
Should You Send Emails Directly from Signals?
It is possible, but it isn’t always a good idea.
Suppose an email operation takes several seconds.
If it runs directly inside a signal during a user’s request, the user may have to wait for the email operation to finish.
A better architecture can be:
Model Event → Signal → Background Task → Email
This allows the main request to finish quickly while the background worker handles the email.
For production applications, this can significantly improve responsiveness.
Django Signals and Business Logic
One of the biggest debates around signals is whether they should contain business logic.
Signals can be useful for small, automatic side effects.
However, putting complex business workflows inside signals can make the application difficult to understand.
For example, imagine:
Order Saved
↓
Signal A
↓
Signal B
↓
Signal C
↓
External API
↓
Notification
A developer looking at the Order creation code may not realize all these operations happen automatically.
This is known as hidden behavior.
Hidden Behavior in Django Signals
Signals can make code harder to trace because the action that triggers a signal and the action performed by the receiver may be located in completely different files.
For example:
orders/services.py
↓
Order saved
↓
signals.py
↓
Notification sent
A developer may modify the order workflow without realizing that a signal is performing additional operations.
This is why signals should be used thoughtfully.
When Should You Use Django Signals?
Signals are a good choice when:
The Action Is a Side Effect
For example:
User created → Create profile
Multiple Components Need to React to an Event
For example:
Payment completed → Notification + Analytics + Audit Log
The Behavior Should Be Automatically Triggered
Signals are useful when you don’t want every caller to remember to perform the same small operation.
The Logic Is Relatively Simple
Small and well-defined signal handlers are easier to maintain.
When Should You Avoid Django Signals?
Signals may not be the best choice when:
The Logic Is Core Business Logic
If an operation is essential to understanding the business workflow, explicit service logic may be clearer.
The Operation Is Complex
Long signal handlers can become difficult to debug.
The Operation Requires Many External Services
For complex workflows involving payments, emails, APIs, and notifications, an explicit service or event-driven architecture may be more appropriate.
The Behavior Must Be Obvious
If developers need to clearly see what happens when a function is called, hiding the behavior inside signals may create confusion.
Django Signals vs Explicit Service Logic
Consider two approaches.
Signal-Based
Create Order
↓
Signal
↓
Update Inventory
Explicit Service
Create Order Service
↓
Create Order
↓
Update Inventory
The second approach makes the workflow more visible.
Neither approach is universally better.
Use signals when automatic decoupled side effects make sense, and use explicit services when the sequence of business operations is important to understand.
Django Signals vs Celery
These technologies solve different problems.
Django Signals
Used to react to events.
Celery
Used to execute tasks asynchronously or in the background.
They can work together.
For example:
Model Event → Signal → Celery Task
But they shouldn’t be treated as interchangeable tools.
Django Signals Best Practices
Follow these practices when working with signals.
Keep Receivers Small
A signal receiver should generally have a clear and limited responsibility.
If the function becomes large, consider moving complex logic into another module.
Avoid Heavy Operations
Don’t perform expensive operations directly inside signals that execute during user requests.
For example:
- Large image processing
- Long API calls
- Large report generation
- Email delivery
These may be better suited for background processing.
Use Transactions Carefully
If a signal triggers external actions, consider whether those actions should happen only after the database transaction successfully commits.
Make Signals Easy to Find
Keep signal definitions organized, commonly in a dedicated signals.py file.
Document Important Signals
If a signal performs an important operation, document what triggers it and what it does.
This helps developers understand hidden application behavior.
Avoid Signal Chains
Try to avoid situations where one signal triggers another signal, which triggers another operation, and so on.
Complex chains can become difficult to debug.
Testing Django Signals
Signals should be tested just like other application logic.
For example, if a profile should be created when a user is created, test that behavior explicitly.
You may want to test:
- Signal executes when expected.
- Signal does not execute unnecessarily.
- Related object is created correctly.
- Errors are handled properly.
- Updates don’t accidentally create duplicates.
- Deletion cleanup works correctly.
Automated tests are especially important because signals can operate behind the scenes.
Debugging Django Signals
When a signal doesn’t work, check:
Is the receiver registered?
Make sure Django loads your signal module.
Is the signal being triggered?
Confirm that the expected model event is actually occurring.
Is the receiver receiving the expected data?
Check the instance and relevant signal arguments.
Is the condition correct?
For example, if you’re checking whether an object was newly created, verify that your condition behaves as expected.
Is another signal interfering?
Complex signal chains can make debugging difficult.
Common Django Signal Mistakes
Forgetting to Register Signals
A receiver won’t work if Django never loads it.
Creating Duplicate Records
For example, a poorly designed post_save receiver might create related objects repeatedly.
Putting Too Much Business Logic in Signals
Large receivers can make applications difficult to understand.
Performing Slow Operations
External API calls and email sending can slow down requests.
Ignoring Transactions
External actions may happen even if a database transaction later fails.
Creating Signal Chains
Multiple dependent signals can make application behavior difficult to trace.
Not Testing Signals
Because signals work automatically, bugs may remain unnoticed without proper tests.
A Practical Django Signal Workflow
A clean signal-based workflow might look like:
Application Event
↓
Django Signal
↓
Small Receiver
↓
Simple Side Effect
For a more complex operation:
Application Event
↓
Signal
↓
Celery Task
↓
Background Processing
For core business logic:
API Request
↓
Service Layer
↓
Business Workflow
↓
Database
Choosing the right approach is more important than simply using signals because they are available.
Real-World Examples of Django Signals
Django Signals can be useful in applications such as:
E-Commerce
Order Created → Update related information
Blogging
Post Published → Create notification
Social Media
User Followed → Create notification
Booking Systems
Booking Confirmed → Trigger notification
Learning Platforms
Course Completed → Generate completion record
File Management
Document Deleted → Clean up stored file
User Management
User Created → Create profile
These are examples where small, well-defined side effects may fit naturally with signals.
Django Signals in Large Applications
In larger applications, signals should be treated as an architectural tool rather than a default solution for every event.
As the application grows, consider whether an operation belongs in:
- A Model
- A View
- A Service
- A Task
- A Signal
- A Management command
- An Event-driven system
A useful design principle is:
Use signals for loosely coupled side effects, not as a replacement for clear business workflows.
Django Signals: Simple Summary
If you remember only a few things, remember these:
Signal
Represents an event.
Receiver
The function that responds to the event.
pre_save
Runs before a model is saved.
post_save
Runs after a model is saved.
pre_delete
Runs before a model is deleted.
post_delete
Runs after a model is deleted.
m2m_changed
Runs when a many-to-many relationship changes.
The overall concept is:
Event → Signal → Receiver → Action
Conclusion
Django Signals provide a convenient way to react automatically to events within a Django application.
They are especially useful for small, decoupled side effects such as creating related records, cleaning up resources, updating secondary information, or triggering notifications.
However, signals should not become a place where all business logic is hidden.
For complex workflows, explicit service functions, background tasks such as Celery, or other architectural patterns may provide better visibility and maintainability.
The key is to use Django Signals when they make the application simpler and more decoupled, not merely because they can perform a particular task.
Once you understand how signals work and when to use them, you can make better architectural decisions when building scalable Django applications.
Frequently Asked Questions
What are Django Signals?
Django Signals allow parts of a Django application to be notified when specific events occur, such as saving or deleting a model.
What is a receiver in Django Signals?
A receiver is a function that is executed when the signal it is connected to is triggered.
What is post_save in Django?
post_save is a Django signal that runs after a model instance has been saved.
What is pre_save in Django?
pre_save runs before a model instance is saved to the database.
What is the difference between pre_save and post_save?
pre_save runs before the model is saved, while post_save runs after the save operation.
When should I use Django Signals?
Use signals for small, automatic, and loosely coupled side effects that should happen when a specific event occurs.
Should I use signals for business logic?
Generally, complex core business logic is better kept in explicit services or workflows where the sequence of operations is easy to see and understand.
Can Django Signals work with Celery?
Yes. A signal can trigger a Celery task so that expensive operations such as emails or image processing happen in the background.
Are Django Signals asynchronous?
No. Django Signals normally execute synchronously. If you need asynchronous processing, you can trigger a background task such as a Celery task from the signal.
Why is my Django Signal not working?
Common causes include the signal module not being loaded, the receiver not being registered, incorrect conditions, or the expected model event not being triggered.
