{"id":9663,"library":"django-cms","title":"Django CMS","description":"django-cms is a lean enterprise content management system built on Django. It provides an intuitive drag-and-drop interface for managing pages and content, extensive plugin architecture, and multilingual support. The current stable version is 5.0.6, with regular patch releases and significant new major versions (like 4.x and 5.x) introducing substantial changes and requiring careful upgrade paths.","status":"active","version":"5.0.6","language":"en","source_language":"en","source_url":"https://github.com/django-cms/django-cms","tags":["django","cms","content management","web framework","python"],"install":[{"cmd":"pip install django-cms==5.0.6 djangocms-text-ckeditor djangocms-picture","lang":"bash","label":"Install Django CMS and common plugins"}],"dependencies":[{"reason":"Core web framework","package":"Django"},{"reason":"Image processing for media management","package":"Pillow"},{"reason":"Efficient tree structure implementation for pages and menus","package":"django-treebeard"},{"reason":"Manages CSS and JavaScript resources","package":"django-sekizai"}],"imports":[{"note":"Import the Page model for custom logic or linking.","symbol":"Page","correct":"from cms.models import Page"},{"note":"Base class for creating custom plugins.","symbol":"CMSPluginBase","correct":"from cms.plugin_base import CMSPluginBase"},{"note":"Registers and manages Apphooks.","symbol":"apphook_pool","correct":"from cms.apphook_pool import apphook_pool"},{"note":"Registers and manages toolbar items.","symbol":"toolbar_pool","correct":"from cms.toolbar_pool import toolbar_pool"},{"note":"Use this field type in custom Django models to embed CMS placeholders.","symbol":"PlaceholderField","correct":"from cms.models.fields import PlaceholderField"}],"quickstart":{"code":"# settings.py\nimport os\n\nBASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n\nINSTALLED_APPS = [\n    'djangocms_admin_style', # Must be before django.contrib.admin\n    'django.contrib.admin',\n    'django.contrib.auth',\n    'django.contrib.contenttypes',\n    'django.contrib.sessions',\n    'django.contrib.messages',\n    'django.contrib.staticfiles',\n    'django.contrib.sites', # Required by CMS\n    'cms', # Must be before 'menus'\n    'menus', # Must be before 'sekizai'\n    'sekizai', # Required for JS/CSS resource management\n    'treebeard', # Required by CMS for page trees\n    'djangocms_text_ckeditor', # Example plugin\n    # Add your project apps here\n]\n\nSITE_ID = 1\n\nMIDDLEWARE = [\n    'django.middleware.security.SecurityMiddleware',\n    'django.contrib.sessions.middleware.SessionMiddleware',\n    'django.middleware.common.CommonMiddleware',\n    'django.middleware.csrf.CsrfViewMiddleware',\n    'django.contrib.auth.middleware.AuthenticationMiddleware',\n    'django.contrib.messages.middleware.MessageMiddleware',\n    'django.middleware.locale.LocaleMiddleware',\n    'cms.middleware.utils.ApphookReloadMiddleware',\n    'cms.middleware.toolbar.ToolbarMiddleware',\n    'cms.middleware.page.PageMiddleware',\n]\n\nTEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [os.path.join(BASE_DIR, 'templates')],\n        'APP_DIRS': True,\n        'OPTIONS': {\n            'context_processors': [\n                'django.template.context_processors.debug',\n                'django.template.context_processors.request',\n                'django.contrib.auth.context_processors.auth',\n                'django.contrib.messages.context_processors.messages',\n                'sekizai.context_processors.sekizai',\n                'cms.context_processors.cms_settings',\n            ],\n        },\n    },\n]\n\nDEBUG = True\nSECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'insecure-dev-key-please-change-this')\nALLOWED_HOSTS = ['*']\nDATABASES = {\n    'default': {\n        'ENGINE': 'django.db.backends.sqlite3',\n        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),\n    }\n}\nSTATIC_URL = '/static/'\nMEDIA_URL = '/media/'\nMEDIA_ROOT = os.path.join(BASE_DIR, 'media')\nSTATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')\n\n# urls.py\nfrom django.contrib import admin\nfrom django.urls import include, path\n\nurlpatterns = [\n    path('admin/', admin.site.urls),\n    path('', include('cms.urls')), # This must be the last URL pattern\n]\n\n# templates/base.html\n# (create this file in your project's 'templates' directory)\n{% load cms_tags sekizai_tags menu_tags %}\n<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\">\n    <title>{% page_attribute \"page_title\" default_value=\"My Site\" %}</title>\n    {% render_block \"css\" %}\n</head>\n<body>\n    {% cms_toolbar %}\n    <header>\n        <h1><a href=\"/\">My Django CMS Site</a></h1>\n        {% show_menu 0 100 100 100 %}\n    </header>\n    <main>\n        {% placeholder \"content\" %}\n    </main>\n    <footer>\n        {% render_block \"js\" %}\n    </footer>\n</body>\n</html>\n","lang":"python","description":"This quickstart outlines the minimal configuration for integrating Django CMS into an existing Django project. It includes essential `INSTALLED_APPS`, `MIDDLEWARE`, `TEMPLATES` context processors, a basic `urls.py` setup, and a simple `base.html` template. After configuring, run `python manage.py makemigrations` (if needed), `python manage.py migrate`, `python manage.py createsuperuser`, and `python manage.py collectstatic`. Then start the server and navigate to `/admin` to create your first page."},"warnings":[{"fix":"Refer to the official Django CMS 5.x upgrade guide and release notes for a detailed migration path. Test thoroughly in a staging environment.","message":"Upgrading from Django CMS 3.x or 4.x to 5.x introduces significant breaking changes. These include refactored template tags, changes to Apphook and plugin registration, and updates to the internal API and JavaScript frontend. A full upgrade guide must be consulted.","severity":"breaking","affected_versions":"< 5.0"},{"fix":"Review all templates using CMS-specific tags and update them according to the 5.x documentation. Pay close attention to `placeholder`, `render_placeholder`, and menu tags.","message":"The template tag syntax has been significantly updated in Django CMS 5.x. Old usages of `{% placeholder 'name' %}` or `{% render_placeholder 'name' page %}` might need to be adjusted, especially for custom rendering or within `with` blocks.","severity":"breaking","affected_versions":"< 5.0"},{"fix":"Ensure `STATIC_URL`, `STATIC_ROOT`, `MEDIA_URL`, and `MEDIA_ROOT` are correctly defined in `settings.py`. Run `python manage.py collectstatic` after any changes to static files or when deploying.","message":"Incorrect configuration of `STATIC_URL`, `STATIC_ROOT`, `MEDIA_URL`, or `MEDIA_ROOT` can lead to missing static assets (CSS/JS) in the Django CMS admin toolbar or broken image/file uploads in the frontend.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `LocaleMiddleware` is before CMS middleware, and `ApphookReloadMiddleware`, `ToolbarMiddleware`, and `PageMiddleware` are present and in the correct order, typically near the end of the `MIDDLEWARE` list.","message":"The order of middleware in `settings.py` is crucial for Django CMS. Incorrect ordering can lead to the toolbar not appearing, apphooks not resolving, or pages not rendering correctly.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Add `{% load cms_tags %}` at the top of any template file that uses Django CMS template tags (e.g., `{% placeholder %}`, `{% cms_toolbar %}`).","cause":"The `cms_tags` template library was not loaded in your Django template.","error":"TemplateSyntaxError: 'cms_tags' is not a registered tag library"},{"fix":"Ensure you have `path('', include('cms.urls'))` in your project's `urls.py`, typically as the *last* pattern in your `urlpatterns` list to catch all CMS pages.","cause":"Django CMS URLs are not correctly included in your project's `urls.py`, or they are placed incorrectly.","error":"NoReverseMatch at / 'cms_page_url' is not a registered namespace"},{"fix":"Use template tags like `{% page_attribute 'page_title' %}` or access title through `page.title` (if language is active) or `page.get_title_obj()` for language-aware operations in Python.","cause":"This error often occurs when upgrading from older Django CMS versions (pre-4.0) where direct access to `page.get_title()` was common. The `Page` model's API has evolved.","error":"AttributeError: 'Page' object has no attribute 'get_title'"},{"fix":"Run `python manage.py migrate` after adding `django-cms` and its required apps to `INSTALLED_APPS`.","cause":"The database migrations for Django CMS (and possibly its dependencies) have not been applied.","error":"OperationalError: no such table: cms_page"}]}