Signals

The signal dispatcher lives in django.dispatch. A signal is an instance of django.dispatch.Signal; a receiver is a callable registered on it; the sender is whatever object the code that fires the signal passes as sender, typically a class (for model signals, the model class) so that receivers can filter on it. Every signal call has the same shape: a mandatory sender plus any keyword arguments the signal documents. Receivers are called one at a time, in the order they were registered, and each call’s return value is collected.

The dispatcher only exists inside one Python process. A signal is not a message queue: nothing is persisted, nothing reaches another server, and a receiver that is slow slows the sender down. Work that must outlive the request or run elsewhere belongs in the tasks framework or Celery, which this section covers on its own pages (a receiver may enqueue such work, see Model signals).

Source: Signals

A receiver is any function or method. It is called with the signal itself as signal, the sender as sender, and the signal’s arguments as keywords. The documentation is firm about the signature: every receiver must accept sender and wildcard keyword arguments, because a signal may gain arguments in a future release and a receiver written as my_receiver(sender) raises a TypeError the moment one is added. The same holds today for any signal that sends extra keywords.

Source: Receiver functions

There are two ways to connect a receiver: call Signal.connect(receiver, sender=None, weak=True, dispatch_uid=None), or decorate the function with django.dispatch.receiver(signal, **kwargs). The decorator accepts one signal or a list of signals and passes the remaining keyword arguments (sender, weak, dispatch_uid) on to connect().

Source: Connecting receiver functions

A test in the scratch project logs in with self.client.login() and asserts the two log records (login grace, then failed login for grace), so both receivers were exercised. The credentials dictionary sent by user_login_failed has the values of keys that look sensitive (password, token, key, secret and similar names) replaced with asterisks by Django before the signal is sent, but the source documents that cleaning as not comprehensive, so a receiver should log only the username, as above; see Authentication for the full login flow.

Strictly speaking registration can happen anywhere, but the official recommendation is to keep receivers in a signals submodule of the app they belong to, and to connect them in AppConfig.ready(). ready() runs once the app registry is completely populated (see Project Structure & Apps), so models can be imported safely there. The documentation advises against defining or importing receivers in the application’s root module or models.py, to limit the side effects of importing code: a signal connected at import time of models.py is connected whenever anything imports the models, including management commands and scripts that never needed it.

Source: Connecting receiver functions

Two details of the example come from the reference page. The post_migrate signal is sent once per app, with an AppConfig as sender, and its apps argument is the migration state after the run, which is the right source of models (like in a data migration) because it matches the schema as the migrations left it, exactly as in a data migration. Handlers of post_migrate must not alter the database schema, because flush also sends it. The reference page also notes that a receiver that uses an AppConfig instance as sender must be connected in ready(), since AppConfig objects are recreated for tests that run with a modified INSTALLED_APPS. Check that the app is installed by its config class ("catalog.apps.CatalogConfig", or just "catalog" when apps.py has a single config) so that ready() actually runs, and run manage.py check and manage.py migrate to see the receiver at work: the scratch project’s tests verify that the Librarians group exists after the test database is migrated.

Source: post_migrate

Two caveats apply to ready() itself. First, the documentation notes that it can run more than once during testing, so a receiver that is a bound method of an instance that may be recreated should be guarded, which is the job of dispatch_uid (next section). Second, the class_prepared signal is sent while the registry is being populated, before ready() runs, so receivers for it cannot be connected there; the reference suggests connecting it from AppConfig.__init__() without importing models or touching the registry. class_prepared is used mostly by Django internally.

Many signals fire constantly (pre_save fires for every save of every model). Passing sender= makes the dispatcher call the receiver only when the sender matches. For model signals the sender is the model class, and the reference page allows a lazy reference with the "app_label.ModelName" string, which avoids circular imports and works with swappable models such as the user model. The scratch project’s custom post_save receiver for settings.AUTH_USER_MODEL shows the pattern, and a test confirms that saving a Book does not trigger a receiver connected for "catalog.Author".

Source: Connecting to signals sent by specific senders

settings.AUTH_USER_MODEL is a lazy string, so this works even for a custom user model; the sibling page Custom User Model & Backends explains why that is the right reference. When the sender is passed as a lazy reference, disconnect() always returns None instead of a boolean, as the documentation notes.

Without dispatch_uid Django identifies a receiver by the identity of its Python object and registers it only once. For a module-level function, a static method or a class method that identity is stable, so connecting the same function twice is a no-op. A bound method is different: the identity belongs to the particular instance, so connecting the same method on a new instance registers an extra receiver. Supplying a unique dispatch_uid (usually a string, but any hashable object works) makes the receiver bind once per distinct value regardless of how many instances or imports there are.

Source: Preventing duplicate signals

The scratch tests run exactly this: connecting two separate Backend instances without a dispatch_uid produces two calls per send(), with one it produces a single call, and disconnect(dispatch_uid=…​) returns True and then False. The other classic source of duplicates, a module that ends up imported under two dotted names so its function objects differ, is also solved by dispatch_uid. Use a namespaced string ("catalog.create_profile") so two apps never collide by accident, and use it on every receiver that has side effects that must not repeat, such as sending an email.

The django.db.models.signals module defines the signals sent by the ORM. The table lists them with their senders and the arguments that matter most.

Source: Model signals

A pre_save receiver is the right place for an automatically derived field, because it runs before the row is written and the change is part of the same INSERT or UPDATE:

Source: pre_save

The remaining built-in signals are all dispatched with send() (the documentation notes that every built-in signal except those in the async request-response cycle is sent with send()).

Source: Signals reference

The authentication framework adds user_logged_in, user_logged_out (both send request and user) and user_login_failed (sends credentials and request), shown in Receiver functions and @receiver. They are documented with the login helpers and are sent by login(), logout() and authenticate(), so they fire for the admin login, for any LoginView and for your own views that call these functions.

Source: Authentication signals

The request signals carry very little information and run on every request, so the reference page itself recommends considering middleware (see Middleware) before using them. A request-scoped receiver cannot see the HttpRequest (only got_request_exception does). A quick check on both servers shows the difference between handlers; the receiver below logs the handler class that request_finished supplies:

Source: request_finished

A custom signal is a Signal() instance created once at module level, conventionally in a module of its own (here catalog/events.py) that both sender and receivers import. The signal does not declare its arguments: the sender is required and every other keyword is by convention. The older providing_args constructor argument, which many tutorials and books use to document them, was removed in Django 4.0, so write the arguments in a docstring or comment instead.

Source: Defining and sending signals

The scratch test connects such a receiver, calls borrow_book(), and asserts the receiver saw the book and that the result is [(on_borrow, "recorded")].

Django 5.0 added Signal.asend() and Signal.asend_robust(), the coroutine counterparts of send() and send_robust(). Receivers may be declared with async def and have the same signature as sync ones, and Django adapts each receiver to the calling style: synchronous receivers called via asend() run through sync_to_async(), and asynchronous receivers called via send() run through async_to_sync(). As with middleware, each adaptation costs a little, so Django groups receivers by whether they are async before calling them, to limit the number of switches.

Source: Sending signals

Grouping has two consequences that the scratch tests confirm. First, order is no longer registration order: an async receiver registered before a sync one may run after it, and the returned list follows execution order (quick first above), so do not rely on order between sync and async receivers. Second, async receivers within one call run concurrently using asyncio.TaskGroup: two receivers that each sleep 0.2 seconds finished together in well under 0.35 seconds. In Django 6.1 this uses a task group (a failure cancels the siblings, as task groups do); older versions (5.0 to 6.0) used asyncio.gather(), which has different cancellation behaviour. The 6.1 release note spells out the change, so code that depends on how an error in one async receiver affects the others should be re-tested when upgrading from 5.2 or 6.0.

Source: Sending signals

Everything the framework sends is dispatched with send() apart from the signals inside the async request-response cycle: in Django’s ASGI handler request_started and request_finished are dispatched with asend(), so async receivers of those two run on the event loop. The check with uvicorn in Request, auth, test and other built-in signals exercised the ASGI path, and the async test client passed AsyncClientHandler as the sender of request_started. Async receivers are the right fit when a receiver awaits I/O (a cache or an HTTP call from async code); keep CPU-bound work and blocking calls out of them. The async ORM, views and middleware that surround these signals are covered on the async pages of this section.

Signal.disconnect(receiver=None, sender=None, dispatch_uid=None) takes the arguments of connect(), returns True if a receiver was disconnected and False otherwise, and may be called with only a dispatch_uid to identify the receiver. Use it for temporary hooks and for cleaning up in tests. Remember that disconnecting a receiver connected with a lazy "app_label.Model" sender always returns None.

Source: Disconnecting signals

Test the observable effect, not the dispatcher: create the user and assert that the profile exists. The tests that accompany this page do exactly that, plus a few focused ones. Whatever a test connects must be disconnected, or it leaks into other tests; addCleanup keeps it tidy:

Source: Testing tools

Two testing signals are useful in their own right. setting_changed is sent when a setting is overridden and when it is restored (enter tells which), so a component that caches a setting value can reset the cache in a receiver; the scratch test asserts the pair ("es", True) and ("en-us", False) for override_settings(LANGUAGE_CODE="es"). The other is template_rendered, on which the test client builds response.context. The test runner, TestCase, captureOnCommitCallbacks and the other helpers are covered on the testing page of this section.

Source: setting_changed

The official documentation carries two warnings that set the tone: signals give the appearance of loose coupling but can quickly lead to code that is hard to understand, adjust and debug, and, where possible, calling the handling code directly is the better option. The reference page adds specific advice for each group: for model signals, consider a helper method on a custom manager, or overriding model methods, before using a signal; for request and response signals, consider middleware first. Two Scoops of Django, one of the books consulted for this section, makes the same argument and calls signals a last resort; its reasoning matches the pitfalls shown above.

The explicit alternative to the profile receiver is a small function that does both steps in one transaction and is called from the view or form that creates users:

Source: Signals

Note that the receiver create_profile and this function overlap on purpose: with both in place a user created through the function would get its profile from whichever runs first, and update_or_create makes the second a harmless update. In real code choose one. A practical set of rules that follow from the pitfalls above:

The books consulted for this section (listed on the section bibliography page) describe signals as they were in Django 1.x and 2.x, and the core mechanism has not changed: @receiver, connect(), sender, dispatch_uid, m2m_changed and registration in ready() all work today as they did then. What differs is at the edges.

Source: Django 6.1 release notes