Install django CMS manually

This how-to guide walks you through manually installing django CMS into a new or existing Django project. For a quick start, see Installing django CMS.

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

Create a new project with djangocms

This section explains how to create a brand new django CMS project using the djangocms command. If you’re adding django CMS to an existing project, skip to Add django CMS to an existing project.

Install the django CMS package

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

What the djangocms command does

You can create a new django CMS project using:

djangocms myproject

This shortcut command performs the following five steps:

  1. Creates a new Django project using a template:

    django-admin startproject myproject --template https://github.com/django-cms/cms-template/archive/5.1.tar.gz

  2. Installs additional optional packages used in the template project:

  3. Runs the migrate command to create the database:

    python -m manage migrate

  4. Prompts for creating a superuser:

    python -m manage createsuperuser

  5. Runs the django CMS check command:

    python -m manage cms check

Project structure

After running djangocms myproject, your project looks like this:

myproject/
    LICENSE
    README.md
    db.sqlite3
    myproject/
        static/
        templates/
            base.html
        __init__.py
        asgi.py
        settings.py
        urls.py
        wsgi.py
    manage.py
    requirements.in

The LICENSE and README.md files can be deleted or replaced. The requirements.in contains dependencies for the project.

Add django CMS to an existing project

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

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_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

CMS_CONFIRM_VERSION4 = True

X_FRAME_OPTIONS = "SAMEORIGIN"

CMS_CONFIRM_VERSION4 ensures you do not accidentally run migrations on a django CMS version 3 database.

Warning

Do not add CMS_CONFIRM_VERSION4 = True to a django CMS version 3 project unless you know what you are doing.

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