Django Signals: The Complete Guide

2025-10-06

Django Python Development

Django signals are one of the framework’s most powerful yet underutilized features. They allow decoupled applications to get notified when certain actions occur elsewhere in the framework, enabling you to build more maintainable, scalable, and responsive applications. In this comprehensive guide, we’ll explore every Django signal, complete with real-world use cases and optimization strategies.

How Django Signals Work: The Foundation

Before diving into specific signals, let’s understand the mechanism behind them.

Django signals operate on a publisher-subscriber pattern. When an event occurs (like saving a model), Django sends a signal that any listener can catch and respond to. This decouples your code — the sender doesn’t need to know who’s listening.

Basic Signal Anatomy

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

@receiver(post_save, sender=User)
def user_saved_handler(sender, instance, created, **kwargs):
    if created:
        print(f"New user created: {instance.username}")

Key Components:

django signals key components

Sender: The model or component triggering the signal
Receiver: Your function that handles the signal
Signal: The event type (e.g., post_save)
Instance: The actual object involved in the event

Setting Up Signals Properly

For signals to work, they must be imported when Django starts. The best practice is to:

Create a signals.py file in your app
Import it in your app’s apps.py:

# apps.py
from django.apps import AppConfig

class MyAppConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'myapp'
    
    def ready(self):
        import myapp.signals

Model Signals: The Core of Django’s ORM Events

Model signals fire during the lifecycle of your database objects. They’re crucial for maintaining data integrity, triggering side effects, and optimizing workflows.

1. pre_init & post_init: Object Instantiation Events

When They Fire:

pre_init: Before a model's __init__() method is called
post_init: After a model instance is fully initialized

Use Case: Tracking Field Changes

from django.db.models.signals import post_init
from django.dispatch import receiver

@receiver(post_init, sender=Article)
def store_original_status(sender, instance, **kwargs):
    """Track original status to detect changes"""
    instance._original_status = instance.status

Optimization Benefit: Detect which fields changed without extra database queries, enabling conditional processing only when necessary.

User Experience Impact: Reduces unnecessary processing, making your application faster and more responsive.

2. pre_save & post_save: The Workhorses of Django Signals

When They Fire:

pre_save: Before Django saves an object to the database
post_save: After Django saves an object to the database

Parameters:

sender: The model class
instance: The actual instance being saved
created: Boolean indicating if this is a new record (post_save only)
update_fields: Set of fields being updated (if specified)

Always check the created flag with post_save signal to differentiate new vs. updated records

Use Case 1: Automatic Slug Generation

@receiver(pre_save, sender=BlogPost)
def generate_slug(sender, instance, **kwargs):
    if not instance.slug:
        from django.utils.text import slugify
        instance.slug = slugify(instance.title)

Use Case 2: Sending Welcome Emails

@receiver(post_save, sender=User)
def send_welcome_email(sender, instance, created, **kwargs):
    if created:
        from django.core.mail import send_mail
        send_mail(
            'Welcome to Our Platform',
            f'Hi {instance.username}, thanks for joining!',
            'noreply@example.com',
            [instance.email],
            fail_silently=True,
        )

Use Case 3: Creating Related Objects

@receiver(post_save, sender=User)
def create_user_profile(sender, instance, created, **kwargs):
    if created:
        UserProfile.objects.create(user=instance)

Optimization Strategy:

@receiver(post_save, sender=Order)
def process_order(sender, instance, created, update_fields, **kwargs):
    # Only process if status changed
    if update_fields is None or 'status' in update_fields:
        if instance.status == 'completed':
            # Send confirmation email asynchronously
            send_order_confirmation.delay(instance.id)

Pro Tips:

Use pre_save for data validation and transformation
Use post_save for side effects (emails, notifications, logging)
Always check the created flag to differentiate new vs. updated records
Avoid recursive saves — they can cause infinite loops

User Experience Impact: Automates workflows (welcome emails, profile creation), provides instant feedback, and maintains data consistency without manual intervention.

3. pre_delete & post_delete: Cleanup and Cascading Actions

When They Fire:

pre_delete: Before Django deletes an object
post_delete: After Django deletes an object

Use Case 1: File Cleanup

@receiver(post_delete, sender=Document)
def delete_file_on_delete(sender, instance, **kwargs):
    """Remove file from storage when model is deleted"""
    if instance.file:
        if os.path.isfile(instance.file.path):
            os.remove(instance.file.path)

Use Case 2: Audit Logging

@receiver(pre_delete, sender=Product)
def log_product_deletion(sender, instance, **kwargs):
    DeletionLog.objects.create(
        model_name='Product',
        object_id=instance.id,
        deleted_by=get_current_user(),
        data=model_to_dict(instance)
    )

Use Case 3: Preventing Accidental Deletions

@receiver(pre_delete, sender=CriticalData)
def prevent_deletion(sender, instance, **kwargs):
    if instance.is_protected:
        raise PermissionDenied("This record cannot be deleted")

Optimization Benefit: Prevents orphaned files that waste storage space, maintains referential integrity, and provides audit trails for compliance.

User Experience Impact: Prevents broken links to deleted files, maintains data consistency, and provides accountability through audit logs.

4. m2m_changed: Many-to-Many Relationship Events

When It Fires:

When a ManyToManyField changes (items added, removed, or cleared)

Parameters:

action: The type of change (pre_add, post_add, pre_remove, post_remove, pre_clear, post_clear)
pk_set: Set of primary keys affected
reverse: Boolean indicating if this is a reverse relation

Use Case 1: Permission Updates

@receiver(m2m_changed, sender=User.groups.through)
def update_user_cache(sender, instance, action, pk_set, **kwargs):
    if action in ['post_add', 'post_remove', 'post_clear']:
        # Clear cached permissions
        cache.delete(f'user_permissions_{instance.id}')

Use Case 2: Course Enrollment Notifications

@receiver(m2m_changed, sender=Course.students.through)
def notify_enrollment(sender, instance, action, pk_set, **kwargs):
    if action == 'post_add':
        students = User.objects.filter(pk__in=pk_set)
        for student in students:
            send_enrollment_confirmation.delay(
                student.email, 
                instance.title
            )

Use Case 3: Inventory Management

@receiver(m2m_changed, sender=Order.products.through)
def update_inventory(sender, instance, action, pk_set, **kwargs):
    if action == 'post_add':
        products = Product.objects.filter(pk__in=pk_set)
        for product in products:
            product.reserved_quantity += 1
            product.save(update_fields=['reserved_quantity'])

Optimization Strategy:

@receiver(m2m_changed, sender=Article.tags.through)
def update_tag_counts(sender, instance, action, pk_set, **kwargs):
    if action == 'post_add':
        # Bulk update instead of individual queries
        Tag.objects.filter(pk__in=pk_set).update(
            article_count=F('article_count') + 1
        )
    elif action == 'post_remove':
        Tag.objects.filter(pk__in=pk_set).update(
            article_count=F('article_count') - 1
        )

User Experience Impact: Real-time updates to enrollment status, accurate inventory tracking, and immediate permission changes improve reliability and user trust.

5. class_prepared: Model Class Registration

When It Fires:

After a model class is fully prepared and registered with Django

Use Case: Dynamic Model Registration

from django.db.models.signals import class_prepared

@receiver(class_prepared)
def add_dynamic_methods(sender, **kwargs):
    """Add methods to all models dynamically"""
    if hasattr(sender, '_meta') and not sender._meta.abstract:
        def get_verbose_name(self):
            return self._meta.verbose_name
        sender.add_to_class('get_verbose_name', get_verbose_name)

Optimization Benefit: Enables metaprogramming and dynamic model enhancement without modifying source code.

Request/Response Signals: HTTP Lifecycle Monitoring

1. request_started & request_finished

When They Fire:

request_started: When Django begins processing an HTTP request
request_finished: When Django finishes sending an HTTP response

Use Case 1: Request Timing

from django.core.signals import request_started, request_finished
from django.dispatch import receiver
import time

request_times = {}

@receiver(request_started)
def start_timer(sender, environ, **kwargs):
    request_times[id(environ)] = time.time()

@receiver(request_finished)
def end_timer(sender, **kwargs):
    request_id = id(sender)
    if request_id in request_times:
        duration = time.time() - request_times.pop(request_id)
        if duration > 1.0:  # Log slow requests
            logger.warning(f"Slow request detected: {duration:.2f}s")

Use Case 2: Connection Pool Management

@receiver(request_finished)
def cleanup_connections(sender, **kwargs):
    """Close idle database connections"""
    from django.db import connection
    connection.close_if_unusable_or_obsolete()

Optimization Benefit: Identifies performance bottlenecks, manages resources efficiently, and prevents connection leaks.
User Experience Impact: Faster page loads through performance monitoring and resource optimization.

2. got_request_exception: Error Handling

When It Fires: When Django encounters an exception during request processing

Use Case 1: Real-time Error Alerting

from django.core.signals import got_request_exception

@receiver(got_request_exception)
def log_exception(sender, request, **kwargs):
    import traceback
    error_details = {
        'url': request.path,
        'method': request.method,
        'user': request.user.username if request.user.is_authenticated else 'Anonymous',
        'traceback': traceback.format_exc()
    }
    
    # Send to error tracking service
    sentry_sdk.capture_exception()
    
    # Alert team for critical endpoints
    if '/api/payment/' in request.path:
        send_urgent_alert.delay(error_details)

Use Case 2: User-Friendly Error Responses

@receiver(got_request_exception)
def handle_api_errors(sender, request, **kwargs):
    if request.path.startswith('/api/'):
        # Log API errors separately
        api_error_logger.error(
            f"API Error: {request.path}",
            extra={'request': request}
        )

Optimization Benefit: Proactive error detection and resolution reduces downtime and improves reliability.
User Experience Impact: Faster bug fixes, reduced error frequency, and better error messages enhance user satisfaction.

Authentication Signals: User Session Management

1. user_logged_in

When It Fires: When a user successfully logs in

Use Case 1: Login Tracking

from django.contrib.auth.signals import user_logged_in

@receiver(user_logged_in)
def log_user_login(sender, request, user, **kwargs):
    LoginHistory.objects.create(
        user=user,
        ip_address=request.META.get('REMOTE_ADDR'),
        user_agent=request.META.get('HTTP_USER_AGENT'),
        timestamp=timezone.now()
    )

Use Case 2: Multi-Device Management

@receiver(user_logged_in)
def limit_concurrent_sessions(sender, request, user, **kwargs):
    from django.contrib.sessions.models import Session
    
    # Get all sessions for this user
    user_sessions = Session.objects.filter(
        expire_date__gte=timezone.now()
    )
    
    # Allow only 3 concurrent sessions
    if user_sessions.count() > 3:
        oldest_sessions = user_sessions.order_by('expire_date')[:user_sessions.count()-3]
        for session in oldest_sessions:
            session.delete()

Use Case 3: Welcome Back Notifications

@receiver(user_logged_in)
def show_last_login(sender, request, user, **kwargs):
    last_login = user.last_login
    if last_login:
        messages.info(
            request, 
            f"Welcome back! Last login: {last_login.strftime('%B %d, %Y at %I:%M %p')}"
        )

User Experience Impact: Enhanced security through session monitoring, personalized welcome messages, and protection against unauthorized access.

2. user_logged_out

When It Fires: When a user logs out

Use Case 1: Cleanup User Data

from django.contrib.auth.signals import user_logged_out

@receiver(user_logged_out)
def clear_user_cache(sender, request, user, **kwargs):
    if user:
        cache.delete_many([
            f'user_preferences_{user.id}',
            f'user_cart_{user.id}',
            f'user_notifications_{user.id}'
        ])

Use Case 2: Activity Logging

@receiver(user_logged_out)
def log_logout(sender, request, user, **kwargs):
    if user:
        ActivityLog.objects.create(
            user=user,
            action='logout',
            session_duration=calculate_session_duration(request)
        )

Optimization Benefit: Frees memory and prevents stale cached data from consuming resources.

3. user_login_failed

When It Fires: When a login attempt fails

Use Case 1: Brute Force Protection

from django.contrib.auth.signals import user_login_failed

@receiver(user_login_failed)
def track_failed_logins(sender, credentials, request, **kwargs):
    username = credentials.get('username')
    ip_address = request.META.get('REMOTE_ADDR')
    
    # Increment failed attempt counter
    cache_key = f'failed_login_{ip_address}_{username}'
    attempts = cache.get(cache_key, 0) + 1
    cache.set(cache_key, attempts, timeout=3600)  # 1 hour
    
    # Block after 5 failed attempts
    if attempts >= 5:
        # Implement blocking logic
        BlockedIP.objects.get_or_create(
            ip_address=ip_address,
            reason=f'Multiple failed login attempts for {username}'
        )
        
        # Send security alert
        send_security_alert.delay(username, ip_address, attempts)

Use Case 2: Security Notifications

@receiver(user_login_failed)
def notify_user_failed_login(sender, credentials, **kwargs):
    username = credentials.get('username')
    try:
        user = User.objects.get(username=username)
        # Only notify on multiple failures
        failures = cache.get(f'notify_failures_{user.id}', 0) + 1
        cache.set(f'notify_failures_{user.id}', failures, 3600)
        
        if failures >= 3:
            send_mail(
                'Suspicious Login Activity',
                'Someone tried to access your account multiple times.',
                'security@example.com',
                [user.email]
            )
    except User.DoesNotExist:
        pass

User Experience Impact: Protects user accounts from unauthorized access, provides security notifications, and prevents account takeovers.

Management Signals: Database Migration Events

1. pre_migrate & post_migrate

When They Fire:

pre_migrate: Before Django runs migrations
post_migrate: After Django runs migrations

Use Case 1: Creating Default Data

from django.db.models.signals import post_migrate
from django.contrib.auth.models import Group, Permission

@receiver(post_migrate)
def create_default_groups(sender, **kwargs):
    # Create default user groups
    editor_group, created = Group.objects.get_or_create(name='Editors')
    if created:
        permissions = Permission.objects.filter(
            codename__in=['add_article', 'change_article']
        )
        editor_group.permissions.set(permissions)

Use Case 2: Data Migration Validation

@receiver(post_migrate)
def validate_critical_data(sender, **kwargs):
    from myapp.models import SystemConfig
    
    # Ensure critical configuration exists
    if not SystemConfig.objects.filter(key='site_name').exists():
        SystemConfig.objects.create(
            key='site_name',
            value='My Application'
        )

Use Case 3: Search Index Initialization

@receiver(post_migrate)
def initialize_search_index(sender, **kwargs):
    if sender.name == 'myapp':
        # Rebuild search index after migrations
        from django.core.management import call_command
        call_command('rebuild_index', interactive=False)

Optimization Benefit: Automates setup tasks, ensures data consistency after schema changes, and eliminates manual post-deployment steps.
User Experience Impact: Reduces deployment errors, ensures the application is properly configured, and minimizes downtime during updates.

Test Signals: Testing and Development

1. setting_changed

When It Fires: When a Django setting is changed (typically during testing)

Use Case: Cache Invalidation During Tests

from django.test.signals import setting_changed

@receiver(setting_changed)
def clear_cache_on_setting_change(sender, setting, value, **kwargs):
    if setting == 'CACHE_MIDDLEWARE_KEY_PREFIX':
        cache.clear()

Optimization Benefit: Ensures tests run with correct configuration, preventing false positives/negatives.

2. template_rendered

When It Fires: When Django renders a template (only in test mode)**

Use Case: Template Testing and Debugging

from django.test.signals import template_rendered

@receiver(template_rendered)
def track_template_usage(sender, template, context, **kwargs):
    """Track which templates are rendered during tests"""
    print(f"Rendered: {template.name}")
    print(f"Context variables: {list(context.keys())}")

Optimization Benefit: Helps debug template issues and verify correct templates are being used in tests.

Database Wrapper Signals: Connection Management

1. connection_created

When It Fires: When a database connection is established

Use Case 1: Database Connection Monitoring

from django.db.backends.signals import connection_created

@receiver(connection_created)
def setup_connection(sender, connection, **kwargs):
    # Set connection parameters for PostgreSQL
    if connection.vendor == 'postgresql':
        with connection.cursor() as cursor:
            cursor.execute("SET TIME ZONE 'UTC'")

Use Case 2: Connection Pool Monitoring

@receiver(connection_created)
def monitor_connections(sender, connection, **kwargs):
    active_connections = cache.get('db_connections', 0) + 1
    cache.set('db_connections', active_connections)
    
    if active_connections > 50:
        logger.warning(f"High database connection count: {active_connections}")

Optimization Benefit: Prevents connection exhaustion, optimizes database settings per connection, and monitors resource usage.
User Experience Impact: Prevents application slowdowns due to connection pool exhaustion, maintains consistent database performance.

Best Practices for Using Django Signals

1. Keep Receivers Simple and Fast

# BAD: Heavy processing in signal
@receiver(post_save, sender=Order)
def process_order(sender, instance, **kwargs):
    generate_invoice(instance)  # Slow
    send_confirmation_email(instance)  # Slow
    update_analytics(instance)  # Slow

# GOOD: Delegate to background tasks
@receiver(post_save, sender=Order)
def process_order(sender, instance, **kwargs):
    process_order_async.delay(instance.id)

2. Avoid Circular Dependencies

# BAD: Can cause infinite loops
@receiver(post_save, sender=Profile)
def update_user(sender, instance, **kwargs):
    instance.user.last_modified = timezone.now()
    instance.user.save()  # This triggers another signal!

# GOOD: Use update() or update_fields
@receiver(post_save, sender=Profile)
def update_user(sender, instance, **kwargs):
    User.objects.filter(pk=instance.user.pk).update(
        last_modified=timezone.now()
    )

3. Use Conditional Logic

@receiver(post_save, sender=Article)
def handle_article_save(sender, instance, created, **kwargs):
    if created:
        # Only for new articles
        notify_subscribers.delay(instance.id)
    elif instance.status == 'published' and instance._original_status != 'published':
        # Only when status changes to published
        publish_to_social_media.delay(instance.id)

4. Disconnect Signals When Needed

from django.db.models.signals import post_save

# Temporarily disable signal
post_save.disconnect(send_notification, sender=Comment)
try:
    # Bulk operations without triggering signals
    Comment.objects.bulk_create(comments)
finally:
    post_save.connect(send_notification, sender=Comment)

5. Test Signal Behavior

from django.test import TestCase, override_settings

class SignalTestCase(TestCase):
    def test_user_profile_created(self):
        user = User.objects.create_user(username='test', email='test@example.com')
        self.assertTrue(UserProfile.objects.filter(user=user).exists())

Performance Optimization Strategies

1. Batch Processing
Instead of processing items individually in signals, batch them:

from django.db.models.signals import post_save
from django.core.cache import cache

@receiver(post_save, sender=Product)
def queue_search_update(sender, instance, **kwargs):
    # Add to batch queue
    queue = cache.get('search_update_queue', set())
    queue.add(instance.id)
    cache.set('search_update_queue', queue, 300)
    
    # Process batch every 100 items
    if len(queue) >= 100:
        update_search_index_batch.delay(list(queue))
        cache.delete('search_update_queue')

2. Selective Signal Firing

# Save without triggering signals
instance.save(skip_signals=True)  # Custom implementation

# Or use update() which doesn't fire signals
Model.objects.filter(pk=instance.pk).update(field=value)

3. Asynchronous Processing

from celery import shared_task

@shared_task
def process_heavy_operation(instance_id):
    instance = MyModel.objects.get(pk=instance_id)
    # Heavy processing here

@receiver(post_save, sender=MyModel)
def handle_save(sender, instance, **kwargs):
    # Offload to background task
    process_heavy_operation.delay(instance.id)

Real-World Project Example: E-commerce Platform

Here’s how signals can work together in a complete system:

# signals.py
from django.db.models.signals import post_save, pre_delete, m2m_changed
from django.contrib.auth.signals import user_logged_in
from django.dispatch import receiver
from .models import Order, Product, User
from .tasks import send_order_email, update_inventory, log_activity

@receiver(post_save, sender=Order)
def handle_order_creation(sender, instance, created, **kwargs):
    if created:
        # Send confirmation email asynchronously
        send_order_email.delay(instance.id)
        
        # Update inventory
        update_inventory.delay(instance.id)
        
        # Create notification
        Notification.objects.create(
            user=instance.user,
            message=f"Order #{instance.id} confirmed"
        )

@receiver(m2m_changed, sender=Order.products.through)
def calculate_order_total(sender, instance, action, **kwargs):
    if action in ['post_add', 'post_remove', 'post_clear']:
        instance.total = sum(p.price for p in instance.products.all())
        instance.save(update_fields=['total'])

@receiver(user_logged_in)
def restore_shopping_cart(sender, request, user, **kwargs):
    # Restore cart from database
    cart_items = CartItem.objects.filter(user=user)
    request.session['cart'] = list(cart_items.values())

@receiver(pre_delete, sender=Product)
def archive_product_data(sender, instance, **kwargs):
    # Archive before deletion for analytics
    ArchivedProduct.objects.create(
        original_id=instance.id,
        name=instance.name,
        sales_count=instance.sales_count,
        revenue=instance.total_revenue
    )

Conclusion: Building Better Django Applications

Django signals are a powerful tool for building decoupled, maintainable applications. By leveraging the right signals at the right time, you can:

Improve Code Organization: Separate concerns and keep your codebase modular
Enhance User Experience: Automate workflows, provide real-time feedback, and maintain data consistency
Optimize Performance: Process tasks asynchronously, batch operations, and manage resources efficiently
Increase Security: Track login attempts, monitor suspicious activity, and maintain audit logs
Simplify Maintenance: Reduce manual tasks, automate deployments, and catch errors proactively

Remember these key principles:

Keep signal receivers simple and fast
Use asynchronous tasks for heavy processing
Avoid circular dependencies and infinite loops
Test signal behavior thoroughly
Monitor performance and optimize bottlenecks

With proper implementation, Django signals transform your application from a collection of isolated components into a responsive, event-driven system that delights users and simplifies development.

django