Django Master Template (Base Template) – A Complete Guide
Last updated 3 weeks, 3 days ago | 84 views 75 5
When building a Django web application, many pages share a common structure — like headers, footers, sidebars, or stylesheets. Rather than repeating this code in every template, Django provides a way to define a Master Template (also called a base template) that child templates can inherit from.
This guide walks you through the why, how, and best practices for setting up a master template in Django.
What Is a Master Template?
A master template is the parent layout file used as the foundation for other pages. It defines:
-
HTML
<head>structure -
Page layout
-
CSS and JavaScript includes
-
Common headers, footers, navbars
Other templates then extend this master template using {% extends %} and override only the necessary blocks.
✅ Benefits of Using a Master Template
-
DRY (Don't Repeat Yourself) code
-
Easier layout updates
-
Consistent design across pages
-
Simplifies maintenance
Step-by-Step: Create and Use a Master Template
Step 1: Setup the Template Directory
Assuming you have an app called myapp, create this folder structure:
myapp/
├── templates/
│ ├── myapp/
│ │ ├── base.html ← master template
│ │ └── home.html ← child template
Make sure Django knows to look in app templates. In settings.py:
TEMPLATES = [
{
...
'APP_DIRS': True,
...
},
]
Step 2: Create the Master Template (base.html)
<!-- templates/myapp/base.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{% block title %}My Site{% endblock %}</title>
<link rel="stylesheet" href="{% static 'css/style.css' %}">
</head>
<body>
<header>
<h1>My Website</h1>
<nav>
<a href="/">Home</a> |
<a href="/about/">About</a>
</nav>
</header>
<main>
{% block content %}
<!-- Default content -->
{% endblock %}
</main>
<footer>
<p>© 2025 My Website</p>
</footer>
</body>
</html>
Step 3: Create a Child Template (home.html)
<!-- templates/myapp/home.html -->
{% extends 'myapp/base.html' %}
{% block title %}Home - My Site{% endblock %}
{% block content %}
<h2>Welcome to the homepage!</h2>
<p>This content is unique to the home page.</p>
{% endblock %}
Step 4: Create the View (views.py)
# views.py
from django.shortcuts import render
def home(request):
return render(request, 'myapp/home.html')
Step 5: Configure URL Mapping (urls.py)
# myapp/urls.py
from django.urls import path
from . import views
urlpatterns = [
path('', views.home, name='home'),
]
Don't forget to include myapp.urls in your project's urls.py.
Adding More Sections with Blocks
You can define multiple blocks in your base template for flexibility:
<!-- base.html -->
<head>
...
{% block head_extra %}{% endblock %}
</head>
<body>
{% block content %}{% endblock %}
{% block scripts %}{% endblock %}
</body>
Then in the child template:
{% block scripts %}
<script src="{% static 'js/main.js' %}"></script>
{% endblock %}
Using Static Files in Master Template
If you are using CSS or JS:
{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}">
Ensure your static files are placed like:
myapp/
├── static/
│ └── css/
│ └── style.css
✅ Best Practices
| Best Practice | Why It Matters |
|---|---|
Use {% block %} strategically |
Avoid unnecessary override complexity |
| Separate layout and content | Makes templates easier to read and extend |
Reuse components via {% include %} |
For headers, footers, navbars, etc. |
Use {% static %} for assets |
Ensures URLs resolve properly in production |
| Use clear naming conventions | Like base.html, dashboard_base.html, etc. |
⚠️ Common Pitfalls
| Mistake | Issue | Solution |
|---|---|---|
❌ Forgetting {% load static %} |
Static files won’t load | Add {% load static %} at the top |
| ❌ Wrong block names | Template inheritance breaks silently | Make sure child templates match block names |
| ❌ Not using app-namespaced folders | Conflicts if multiple apps use same template name | Use templates/myapp/template.html |
❌ Missing {% extends %} |
Child template renders as standalone HTML | Always extend the master template |
Full Example Recap
File: base.html
<!DOCTYPE html>
<html>
<head>
<title>{% block title %}My Site{% endblock %}</title>
{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}">
</head>
<body>
<header><h1>My Site</h1></header>
<main>
{% block content %}{% endblock %}
</main>
<footer>© 2025 My Site</footer>
</body>
</html>
File: home.html
{% extends 'myapp/base.html' %}
{% block title %}Home{% endblock %}
{% block content %}
<p>This is the homepage content.</p>
{% endblock %}
Conclusion
Creating and using a master template in Django:
-
Keeps your HTML DRY and manageable
-
Makes your project easy to scale
-
Enforces a consistent look and feel
It's a foundational technique every Django developer should master.
Next Steps
-
Learn about
{% include %}and custom tags -
Add dynamic navigation based on user login
-
Create different master templates for admin/user areas
