How to Set Up Django CMS in an Existing Django Project

When You Need This

I had a Django app that did one job well (a time-tracking tool) and I wanted a blog on it. Writing a page model and an editor for every content page is a week of work you should not do. Django CMS gives you a page tree, a WYSIWYG editor, plugins and a Filer-managed media library, and lets you attach it to a project that already exists.

This is the "add it to something that already works" path, which is different from the tutorial path of starting with a CMS-shaped project. The installation is easy; not breaking your existing URLs is the part that needs care.

A photorealistic shot of a laptop showing a code editor with a Django settings file open, a second window with a website page tree, a coffee cup on a wooden desk, daylight, realistic photography, no legible text.

Check Compatibility Before You Install

Django CMS is tightly coupled to Django versions, and installing the wrong pair produces confusing import errors rather than a clear failure. Look at the compatibility table in the django-cms docs for your Django version before you pin anything.

Rules that hold regardless:

  • Pin Django and the CMS packages in requirements.txt. Do not let a pip install upgrade Django underneath you.
  • django-cms 4.x assumes Django 3.2 or newer; older CMS releases do not support modern Django at all.
  • The plugin set is separate: text editor, link, file, picture, video, snippet. Install the ones you need and pin them with the same version family.

Start from a snapshot of your environment:

pip freeze > requirements-before.txt

That file is your rollback.

Install and Configure

pip install django-cms django-treebeard django-sekizai django-classy-tags \
            djangocms-admin-style django-filer django-reversion \
            djangocms-text-ckeditor djangocms-link djangocms-file \
            djangocms-picture djangocms-snippet djangocms-style

In settings.py, add the CMS apps and its dependencies to INSTALLED_APPS. Order matters: cms must come before your own apps that render CMS content, and treebeard before cms.

INSTALLED_APPS = [
    # django core apps...
    "cms",
    "menus",
    "sekizai",
    "treebeard",
    "filer",
    "easy_thumbnails",
    # editor + plugins
    "djangocms_text_ckeditor",
    "djangocms_link",
    "djangocms_file",
    "djangocms_picture",
    "djangocms_snippet",
    "djangocms_style",
    # your apps...
]

Add the context processor the CMS needs, or pages render without their plugin content:

TEMPLATES[0]["OPTIONS"]["context_processors"] += [
    "sekizai.context_processors.sekizai",
    "cms.context_processors.cms_settings",
]

Add the middleware:

MIDDLEWARE += [
    "cms.middleware.utils.ApphookReloadMiddleware",
    "cms.middleware.user.CurrentUserMiddleware",
    "cms.middleware.page.CurrentPageMiddleware",
    "cms.middleware.toolbar.ToolbarMiddleware",
    "cms.middleware.language.LanguageCookieMiddleware",
]

Then add a CMS_TEMPLATES setting pointing at your base template, and migrate:

python manage.py migrate
python manage.py cms check

cms check is worth running even when things appear fine — it reports misconfiguration that otherwise shows up as a blank toolbar weeks later.

A photorealistic close-up of a laptop screen showing a terminal with migration output lines and a green success message, a second monitor blurred with a web page, cool screen light in a dim room, realistic photography, no legible text.

The URL Config Is Where This Goes Wrong

This is the part that breaks existing projects.

Django CMS registers pages at whatever URL they have, which means the CMS URL include must be last, catching anything your own apps did not resolve:

from django.conf import settings
from django.conf.urls.static import static
from django.urls import include, path, re_path
import cms.urls

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("myblog.urls")),
    path("", include("myapp.urls")),
    # CMS last: it matches anything left over
    re_path(r"^", include(cms.urls)),
]

Put cms.urls anywhere other than last and your existing views start returning CMS 404 pages, because the page resolver claimed the path first. I have made this mistake and it presents as "my app randomly broke", not as a URL error.

If you mounted the admin behind a conditional (as in the remove-admin-from-production pattern), the CMS catch-all belongs inside the same branch, after your apps.

After It Works

Create the page tree in the admin, then create the home page explicitly — the CMS will not invent one, and an empty page tree looks like a broken install.

Set CMS_LANGUAGES if you are not using English only. The default is en and pages created under the wrong language code disappear when you switch.

Point your template at Sekizai tags. Your base template needs {% load cms_tags sekizai_tags %} and {% render_block "css" %} / {% render_block "js" %} in the head and body. Without them, plugin CSS and editor scripts do not load and the toolbar misbehaves in ways that look like JavaScript bugs.

Watch the static files. Ckeditor ships its own assets; run collectstatic and confirm they are served before you conclude the editor is broken.

A photorealistic shot of a laptop screen showing a CMS admin page tree with several nested pages, a hand on the trackpad, a printed note with URL patterns beside the keyboard, daylight, realistic photography, no legible text.

The Honest Trade-Off

Adding a CMS to a working Django project costs you a dependency tree, a version-coupling constraint on Django itself, and a middleware stack on every request. For a site with a handful of pages, a simple Page model with a markdown field is less work and less to maintain.

It earns its place when non-developers need to edit pages, when you want a page tree with menus and revision history, or when you are past the point where hand-written views are worth it. For a blog on your own app, it is a reasonable call. For three static pages, it is not.

Don't trust the download button. Trust the hash.

If this was useful, More hands-on tech guides at TechGeek. No pressure — read it whenever it's useful.


Luke Keam
Spot a bug or want a custom utility built? I'd love to hear from you. Get in touch
Luke Keam | techgeek.biz