CKEditor 5 for Django

0.2.20 · active · verified Thu Apr 16

django-ckeditor-5 is a Django application that seamlessly integrates the modern CKEditor 5 rich text editor into Django projects, offering an intuitive content creation experience. It provides features like text formatting, image uploads, tables, and code blocks, making it highly customizable. This package is specifically for CKEditor 5, distinct from the older `django-ckeditor` which uses CKEditor 4. The current version is 0.2.20, with a generally active release cadence.

Common errors

```
CKEditor 5 textarea displays as plain text input, no rich text editor functionality.
```
cause The CKEditor 5 JavaScript and CSS assets have not been loaded, most commonly due to missing `{{ form.media }}` in the template.

fix Ensure `{{ form.media }}` is present in your HTML template, preferably within the `<head>` or before the form, to load the necessary static files for the widget.
```
Image/file uploads fail or images do not display after upload.
```
cause Incorrectly configured `MEDIA_ROOT` and `MEDIA_URL` settings in `settings.py`, or the URL pattern for media handling is not included.

fix Set `MEDIA_ROOT` to an absolute path for uploaded files and `MEDIA_URL` to the public URL. Ensure Django's media URL patterns are correctly configured in your project's `urls.py` for serving uploaded files.
```
WARNINGS: ?: (ckeditor.W001) django-ckeditor bundles CKEditor 4.x.x which isn't supported anymore...
```
cause You have accidentally installed or are using the old `django-ckeditor` package (for CKEditor 4) instead of `django-ckeditor-5`.

fix Uninstall `django-ckeditor` if present (`pip uninstall django-ckeditor`) and install `django-ckeditor-5` (`pip install django-ckeditor-5`). Update your `INSTALLED_APPS` and model/form imports to use `django_ckeditor_5`'s components.

Warnings

breaking This library is for CKEditor 5, which is a complete rewrite from CKEditor 4. Code and configuration for the older `django-ckeditor` (which uses CKEditor 4) are not compatible and will not work.
Fix: Ensure you are installing `django-ckeditor-5` and following its specific documentation. Do not confuse it with `django-ckeditor`.
gotcha When using `CKEditor5Widget` in forms, especially outside of the Django admin, you MUST include `{{ form.media }}` in your HTML template's `<head>` or before the form. Without it, CKEditor 5's JavaScript and CSS assets will not load, and the editor will not render or function correctly.
Fix: Add `{{ form.media }}` inside the `<head>` tag or within the `<body>` before your form in the template where the CKEditor 5 field is used.
gotcha Enabling file/image uploads without proper validation or restrictions can pose a security risk. The library warns that uploaded files are not validated by default, and allowing generic file uploads disables image-specific validation.
Fix: Implement robust server-side validation for uploaded files (e.g., file type, size, content scanning). Consider restricting file types or limiting uploads to trusted users. Configure `CKEDITOR_5_MAX_FILE_SIZE` in settings.py to limit file sizes.

Install

pip install django-ckeditor-5 Install stable release

Imports

django_ckeditor_5
```
INSTALLED_APPS = ['django_ckeditor_5']
```
Must be added to Django's INSTALLED_APPS in settings.py.
CKEditor5Field
```
from django_ckeditor_5.fields import CKEditor5Field
```
Used in Django models for rich text content.
CKEditor5Widget
```
from django_ckeditor_5.widgets import CKEditor5Widget
```
Used in Django forms to render the CKEditor 5 editor.
CKEDITOR_5_CONFIGS
```
CKEDITOR_5_CONFIGS = {'default': {...}}
```
A dictionary in settings.py to configure editor toolbars, language, and other options.

Quickstart

To quickly integrate `django-ckeditor-5`, first add `django_ckeditor_5` to your `INSTALLED_APPS` and define `MEDIA_URL`, `MEDIA_ROOT`, and `CKEDITOR_5_CONFIGS` in your `settings.py`. Then, use `CKEditor5Field` in your Django models for rich text fields and `CKEditor5Widget` in your forms. Ensure `{{ form.media }}` is included in your templates for the editor to render correctly.

import os
from django.db import models
from django.forms import ModelForm
from django.conf import settings
from django_ckeditor_5.fields import CKEditor5Field
from django_ckeditor_5.widgets import CKEditor5Widget

# settings.py additions (example)
# INSTALLED_APPS = [
#     ...,
#     'django_ckeditor_5',
# ]
# MEDIA_URL = '/media/'
# MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
# CKEDITOR_5_CONFIGS = {
#     'default': {
#         'toolbar': ['heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'blockQuote', 'imageUpload', 'fileUpload'],
#         'language': 'en',
#         'width': 'auto'
#     }
# }

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = CKEditor5Field(verbose_name='Rich Content', config_name='default')

    def __str__(self):
        return self.title

class ArticleForm(ModelForm):
    class Meta:
        model = Article
        fields = '__all__'
        widgets = {
            'content': CKEditor5Widget(config_name='default')
        }

# In a Django template, if using a form:
# {% extends 'base.html' %}
# {% block content %}
#   <form method="POST">
#     {{ form.media }}  <!-- IMPORTANT: Don't forget this! -->
#     {% csrf_token %}
#     {{ form.as_p }}
#     <button type="submit">Submit</button>
#   </form>
# {% endblock content %}

view raw JSON →