Switches are simple booleans: they are on or off, for everyone, all the time. They do not require a request object and can be used in other contexts, such as management commands and tasks.

Switch Attributes

Switches can be administered through the Django admin site or the command line. They have the following attributes:

Name:The name of the Switch.
Active:Is the Switch active or inactive.
Note:Describe where the Switch is used.

Custom Switch Models

For many cases, the default Switch model provides all the necessary functionality. If you would like additional fields not supported by the default Switch model, you can use a custom Switch model.

An application needs to define a WAFFLE_SWITCH_MODEL settings. The default is waffle.Switch but can be pointed to an arbitrary object.


It is not possible to change the Switch model and generate working migrations. Ideally, the Switch model should be defined at the start of a new project. This is a limitation of the swappable Django magic. Please use magic responsibly.

The custom Switch model must inherit from waffle.models.AbstractBaseSwitch.

When using a custom Switch model, you must run Django’s makemigrations before running migrations as outlined in the installation docs.

If you need to reference the class that is being used as the Switch model in your project, use the get_waffle_model('SWITCH_MODEL') method. If you reference the Switch a lot, it may be convenient to add Switch = get_waffle_model('SWITCH_MODEL') right below your imports and reference the Switch model as if it had been imported directly.


# settings.py
WAFFLE_SWITCH_MODEL = 'myapp.Switch'

# models.py
from waffle.models import AbstractBaseSwitch, CACHE_EMPTY

class Switch(AbstractBaseSwitch):

    owner = models.CharField(
        help_text=_('The individual/team who owns this switch.'),

# admin.py
from waffle.admin import SwitchAdmin as WaffleSwitchAdmin

class SwitchAdmin(WaffleSwitchAdmin):
    raw_id_fields = tuple(list(WaffleSwitchAdmin.raw_id_fields) + ['owner'])
admin.site.register(Switch, SwitchAdmin)

Auto Create Missing

When a switch is evaluated in code that is missing in the database the switch returns the WAFFLE_SWITCH_DEFAULT value but does not create a switch in the database. If you’d like waffle to create missing switches in the database whenever it encounters a missing switch you can set WAFFLE_CREATE_MISSING_SWITCHES to True. Missing switches will be created in the database and the value of the Active switch attribute will be set to WAFFLE_SWITCH_DEFAULT in the auto-created database record.

Log Missing

Whether or not you enabled Auto Create Missing Switch, it can be practical to be informed that a switch was or is missing. If you’d like waffle to log a warning, error, … you can set WAFFLE_LOG_MISSING_FLAGS to any level known by Python default logger.