Install django CMS manually

This how-to guide walks you through manually installing and configuring django CMS, showing every setting that the automated djangocms command otherwise writes for you. If you prefer the automated setup, follow the installation tutorial for a new project, or Add django CMS to an existing project for an existing one.

This guide assumes you have basic familiarity with Python and Django.

Set up a project

Check the Python/Django requirements for this version of django CMS.

Important

We strongly recommend doing all of the following steps in a virtual environment.

python3 -m venv .venv  # create a virtualenv
source .venv/bin/activate  # activate it
pip install --upgrade pip  # Upgrade pip

Then install django CMS:

pip install django-cms

If you are starting from scratch, create a plain Django project first:

django-admin startproject myproject
cd myproject

If you are adding django CMS to an existing project, work from your project’s root directory (the one containing manage.py) instead. All of the following steps apply to both cases.

Required configuration

To add django CMS to a Django project, you need to install dependencies and modify settings.py and urls.py.

Tip

The steps in this section can be automated by running djangocms . from your project directory — see Add django CMS to an existing project. The rest of this guide describes how to perform the same steps by hand.

Install required packages

Add django CMS and its dependencies to your requirements file:

django-cms>=4.1
django-sekizai
django-treebeard

Or install directly:

pip install django-cms

For a fully-featured setup, also install recommended plugins:

pip install djangocms-text djangocms-frontend django-filer djangocms-versioning djangocms-alias

INSTALLED_APPS

Add to INSTALLED_APPS (order matters):

INSTALLED_APPS = [
    # Add before django.contrib.admin for admin styling (optional)
    "djangocms_simple_admin_style",

    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",  # Required by django CMS

    # django CMS core
    "cms",
    "menus",
    "treebeard",
    "sekizai",

    # Recommended plugins (if installed)
    "filer",
    "easy_thumbnails",
    "djangocms_text",
    "djangocms_frontend",
    "djangocms_frontend.contrib.grid",
    "djangocms_frontend.contrib.image",
    "djangocms_frontend.contrib.link",
    "djangocms_versioning",
    "djangocms_alias",

    # Your existing apps
    # ...
]

Required settings

Add to settings.py:

SITE_ID = 1

X_FRAME_OPTIONS = "SAMEORIGIN"

Language settings

django CMS requires the LANGUAGES setting:

LANGUAGES = [
    ("en", "English"),
    ("de", "German"),
    ("it", "Italian"),
]
LANGUAGE_CODE = "en"

Database

django CMS requires a relational database. SQLite works for development:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

For production, use PostgreSQL, MySQL, or MariaDB:

pip install psycopg2     # for PostgreSQL
pip install mysqlclient  # for MySQL or MariaDB

MIDDLEWARE

Add to MIDDLEWARE (order matters):

MIDDLEWARE = [
    "cms.middleware.utils.ApphookReloadMiddleware",  # Optional, must be first
    "django.middleware.security.SecurityMiddleware",
    # ... existing middleware ...
    "django.middleware.locale.LocaleMiddleware",  # After SessionMiddleware
    # ... existing middleware ...
    "cms.middleware.user.CurrentUserMiddleware",
    "cms.middleware.page.CurrentPageMiddleware",
    "cms.middleware.toolbar.ToolbarMiddleware",
    "cms.middleware.language.LanguageCookieMiddleware",
]

ApphookReloadMiddleware is optional but recommended for apphook reloading.

TEMPLATES

Add sekizai to INSTALLED_APPS and configure context processors:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                # ... existing context processors ...
                "django.template.context_processors.i18n",
                "sekizai.context_processors.sekizai",
                "cms.context_processors.cms_settings",
            ],
        },
    },
]

CMS_TEMPLATES

django CMS requires at least one template. Add CMS_TEMPLATES to settings:

CMS_TEMPLATES = [
    ("home.html", "Home page template"),
]

Create a templates directory and add home.html:

{% load cms_tags sekizai_tags %}
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{% page_attribute "page_title" %}</title>
    {% render_block "css" %}
</head>
<body>
    {% cms_toolbar %}
    <main>
        {% placeholder "content" %}
    </main>
    {% render_block "js" %}
</body>
</html>

Key template tags:

  • {% load cms_tags sekizai_tags %} loads required template tag libraries

  • {% page_attribute "page_title" %} extracts the page’s title

  • {% render_block "css" %} and {% render_block "js" %} load CSS and JavaScript

  • {% cms_toolbar %} renders the django CMS toolbar

  • {% placeholder "content" %} defines where plugins can be inserted

If using django-filer, add thumbnail configuration:

THUMBNAIL_HIGH_RESOLUTION = True
THUMBNAIL_PROCESSORS = (
    "easy_thumbnails.processors.colorspace",
    "easy_thumbnails.processors.autocrop",
    "filer.thumbnail_processors.scale_and_crop_with_subject_location",
    "easy_thumbnails.processors.filters",
)

urls.py

Add CMS URLs using i18n_patterns:

from django.conf import settings
from django.conf.urls.i18n import i18n_patterns
from django.conf.urls.static import static
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    # Non-i18n URLs (if any)
]

urlpatterns += i18n_patterns(
    path("admin/", admin.site.urls),
    # Your existing app URLs
    # path("myapp/", include("myapp.urls")),
    # CMS URLs - must be last (catch-all)
    path("", include("cms.urls")),
)

# For development only
if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Media files

Configure media file handling in settings.py:

MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

For production, configure proper media file serving per Django’s documentation.

Run migrations

Create database tables and verify configuration:

python manage.py migrate
python manage.py createsuperuser  # If you don't have one
python manage.py cms check
python manage.py runserver

Visit http://127.0.0.1:8000 and log in to start creating pages.

Optional plugins

django CMS uses plugins to handle content. The djangocms command installs recommended plugins automatically. If you installed manually, consider adding these.

Django Filer

Django Filer provides file and image management.

pip install django-filer>=3.0

Add to INSTALLED_APPS:

"filer",
"easy_thumbnails",

djangocms-text

djangocms-text provides rich text editing.

pip install djangocms-text

Add djangocms_text to INSTALLED_APPS.

djangocms-frontend

djangocms-frontend adds Bootstrap 5 support.

pip install djangocms-frontend

Add to INSTALLED_APPS:

"djangocms_frontend",
"djangocms_frontend.contrib.accordion",
"djangocms_frontend.contrib.alert",
"djangocms_frontend.contrib.badge",
"djangocms_frontend.contrib.card",
"djangocms_frontend.contrib.carousel",
"djangocms_frontend.contrib.collapse",
"djangocms_frontend.contrib.content",
"djangocms_frontend.contrib.grid",
"djangocms_frontend.contrib.image",
"djangocms_frontend.contrib.jumbotron",
"djangocms_frontend.contrib.link",
"djangocms_frontend.contrib.listgroup",
"djangocms_frontend.contrib.media",
"djangocms_frontend.contrib.tabs",
"djangocms_frontend.contrib.utilities",

djangocms-versioning and djangocms-alias

Install for publishing workflow and reusable content blocks:

pip install djangocms-versioning djangocms-alias

Add to INSTALLED_APPS:

"djangocms_versioning",
"djangocms_alias",

Run migrations

After installing plugins:

python manage.py migrate

Verify your installation

Use django CMS’s built-in check command to verify your configuration:

python manage.py cms check

This checks your configuration, applications, and database, reporting any problems. Run it after each configuration step to verify progress.

Next steps