The Messages Framework

Reviewed & published by Brayan K

Django's messages framework is a built-in system for showing one-time "flash" notifications — short status messages like "Profile saved!" or "Login failed" that appear once after an action and then disappear, surviving the redirect that usually follows a form submission.

Learn The Messages Framework in our free Django course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Django course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

In this lesson you'll learn how to add messages with messages.success() , messages.error() , messages.info() , and messages.warning() , how to display them in a template, and how message tags let you style each level differently.

What You'll Learn in This Lesson

1 Adding Messages in a View

The messages framework lets a view attach a short notification to the current request. You import django.contrib.messages as messages and call one of its level methods, passing the request and the text to show.

The most common pattern is "do something, add a message, then redirect." Because the message is stored between the redirect and the next page, the user reliably sees it even though they land on a brand-new request.

2 Displaying Messages in a Template

Once a view has added messages, your template displays them by looping over the messages variable that Django's context processor makes available. Each message has a tags attribute (like success or error ) you can drop straight into a CSS class.

Here alert- {{ message.tags }} renders to something like alert-success or alert-error , letting you give each severity its own colour. Messages are consumed once read, so they appear exactly once and then vanish.

3 Message Levels and Tags

Django provides five severity levels, each with its own convenience method and default tag. Choosing the right one tells the user how important a notification is and lets your CSS colour it appropriately.

• messages.debug() — development-only messages, hidden in production.
• messages.info() — neutral informational notices.
• messages.success() — an action completed successfully.
• messages.warning() — something the user should be careful about.
• messages.error() — an action failed.

If your CSS framework expects different class names (for example Bootstrap uses danger instead of error ), you can remap the tags in settings.py with MESSAGE_TAGS .

🎯 Your Turn: Pick the Right Level

Fill in the blank with the correct messages method so a successful save shows a green success notification.

Why Your Messages Don't Show Up

By far the most common problem with this framework is adding a message and seeing nothing. Almost always it is one of three settings, because the framework needs all three working together — and each failure looks different.

Missing middleware is the loud one. Django raises a MessageFailure the moment you call messages.success() :

A missing context processor is the quiet one — no error at all, the view runs fine, and {% for message in messages %} simply loops over nothing, because the template never received the variable.

startproject gives you all three, which is why this usually bites on a hand-rolled settings file. If you genuinely need to add messages somewhere they may not be configured — a management command, say — pass fail_silently=True and the call becomes a no-op instead of raising.

Levels, extra_tags and Where Messages Are Stored

Each level is a number, and the ordering is worth knowing because MESSAGE_LEVEL filters on it — anything below the threshold is silently dropped. Note that success is 25 , between info and warning, not above them:

That is why MESSAGE_LEVEL = 30 hides your success messages along with debug and info — a surprise if you assumed success outranked a warning.

For styling one specific message differently, extra_tags appends to the tag string without changing the level:

Storage defaults to django.contrib.messages.storage.fallback.FallbackStorage , which puts messages in a cookie and spills over into the session when they will not fit — cookies cap at about 4KB. Set MESSAGE_STORAGE to the session backend if you would rather never put message text in a cookie. Either way messages are read-once: iterating them in a template marks them consumed, so they do not reappear on the next page.

Common Errors (And How to Fix Them)

❌ Messages added but nothing shows on the page

Your template never loops over the messages variable.

✅ Fix: add a {% for message in messages %} loop to your base template.

❌ MessageFailure: You cannot add messages without...

The message middleware or context processor is missing.

✅ Fix: ensure django.contrib.messages is in INSTALLED_APPS and its middleware is enabled.

You rendered the messages list more than once on the page.

✅ Fix: loop over messages in exactly one place, usually the base template.

📋 Quick Reference

Call

What It Does

messages.success(request, text)

Add a success-level message

messages.error(request, text)

Add an error-level message

messages.info(request, text)

Add a neutral informational message

message.tags

CSS-friendly tag for the message level

🏆 Mini Challenge: Checkout Notifier

Write a function that adds the right message for each checkout outcome: success when paid, warning when low stock, and error when the card is declined.

❓ Frequently Asked Questions

Lesson complete — you can flash messages to your users!

You now know how to add messages with the level methods, display them in a template by looping over messages , and style each level using its tag or a custom MESSAGE_TAGS mapping.

🚀 Up next: User Authentication — log users in and out, and protect views with login_required.

Practice quiz

Continue this course

• Previous: URL Namespacing
• Next: User Authentication