Add django CMS to an existing project

You can add django CMS to an existing Django project with a single command:

pip install django-cms
djangocms .

Run it from the project root (the directory containing manage.py), with your project’s virtual environment activated.

Warning

The command makes automated, best-effort edits to your settings and urls files. Make sure your project is under version control (or backed up) so you can review every change afterwards. The command asks for confirmation before changing anything.

Tip

Run it with --dry-run first to preview every change as a unified diff, without writing any files or installing packages:

djangocms . --dry-run

What the command does

The command reads the settings module from manage.py and updates your project files:

  • adds the django CMS apps (and those of the selected add-ons) to INSTALLED_APPS,

  • adds the django CMS middleware and template context processors,

  • appends required settings such as SITE_ID, LANGUAGES (derived from your LANGUAGE_CODE) and CMS_TEMPLATES if they are missing,

  • adds the django CMS url patterns to your ROOT_URLCONF,

  • creates a templates directory with a minimal base template if your project has none yet.

Existing entries are never duplicated, so the command is safe to run again.

It then lists the required packages and asks whether to install them. If you agree, it installs them, runs the database migrations and validates the installation with cms check.

Choosing options

The same options as for creating a new project are available, for example:

djangocms . --mode headless --no-versioning

selects the headless mode (content is served through a REST API instead of HTML pages) and skips content versioning. See the djangocms command reference for all options and their defaults.

Review the changes

The edits are best-effort: projects with heavily customized settings (for example, split settings modules or settings computed at runtime) may need manual adjustments. After running the command:

  • review the diff of your settings and urls files,

  • start the development server with python -m manage runserver,

  • log in with an existing superuser account and check that the toolbar appears.

No superuser is created when installing into an existing project; create one with python -m manage createsuperuser if needed.

Prefer full control?

If you would rather apply every change yourself, follow the manual configuration steps, which walk through each setting the command writes for you.