How to integrate CKEditor 5 into Django 6

▶

If you are looking for a simple and functional way to add a rich text editor in Django, CKEditor is, without a doubt, one of the best options. In my case, I am using it directly in the Django admin, with full HTML content and image uploading working smoothly, and the integration is much simpler than it seems.

In this guide, I explain how to integrate CKEditor 5 in Django step by step, which package to choose today, and how to get it working correctly without weird configurations or unnecessary hacks.

We also have the image upload part, which works perfectly. We hit save, right-click, open image... and there you can see it.

What is CKEditor and why use it with Django

CKEditor is a WYSIWYG (What You See Is What You Get) editor that allows you to create rich HTML content without writing code by hand. It is ideal for:

• Blog posts
• Content pages
• Long fields in the admin
• CMSs built with Django

The main advantage is that the generated HTML is exactly what you edit. In the end, it's a matter of style and configuration, but you have the control.

CKEditor 4 vs CKEditor 5: which one to use today

This is where many tutorials become outdated.

There are two very similar packages:

• django-ckeditor → CKEditor 4 (obsolete)
• django-ckeditor-5 → CKEditor 5 (current)

Although both "work", I do not recommend using django-ckeditor today. It is based on CKEditor 4, which is no longer the modern version of the editor.

My clear recommendation is to use django-ckeditor-5, which is based on CKEditor 5 and fits better with current projects.

Installation:

pip install django-ckeditor-5

Ways to install CKEditor in Django

This is very simple. We actually have three ways:

1. Manual installation
   1. Possible, but unnecessary today.
2. django-ckeditor (CKEditor 4)
   1. Works, but it is outdated.
3. django-ckeditor-5 (recommended)
   1. It is the cleanest, most modern, and simplest option.

For the rest of the article, we assume you are using django-ckeditor-5.

Installation

One of these packages is called django-ckeditor, which I do not recommend because it is for version 4, as you can see here:

$ pip install django-ckeditor

The other has exactly the same name but with a 5 at the end, which is for version 5 (the most current) and is the one I recommend:

$ pip install django-ckeditor-5

Basic configuration in Django (MEDIA and files) - django-ckeditor-5

In this section, we are going to see the steps to configure CKEditor 5 in Django.

We define the Django settings:

settings.py

STATIC_URL = '/static/'
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

This indicates that now ALL uploaded files will be established in /media/images/ within the project; this includes the FileField fields of the models.

Additionally, we configure the MEDIA_ROOT which indicates the physical storage where the files are saved:

settings.py

MEDIA_ROOT = os.path.join(BASE_DIR, 'media') # EX /home/andres/proyect/media/

Finally, we add:

<Project>\urls.py

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    ***
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

To be able to serve the files that are in MEDIA_ROOT when we access a URL that starts with MEDIA_URL.

We configure it in the settings file, both the package and the options we want it to have in the toolbar:

settings.py

INSTALLED_APPS = [ *** 'django_ckeditor_5', ]

Configure the toolbar and options

CKEditor 5 allows multiple configurations. In this example, we use a simple but functional default configuration:

settings.py

CKEDITOR_5_CONFIGS = {
   'default': {
       'toolbar': {
           'items': [
               'heading', '|',
               'bold', 'italic', 'link',
               'bulletedList', 'numberedList',
               'blockQuote', 'imageUpload',
           ],
       },
   },
}

Here you can customize everything you want. In my case, I left something simple, but enough to create real content without overloading the editor.

We can have multiple configurations, although, in this example, we only create one which is the default; in it, we must configure the options that will be available.

Using CKEditor in models and in the admin

To use CKEditor, you only need to define the field correctly in your models.

from django.db import models
from django_ckeditor_5.fields import CKEditor5Field
class Post(models.Model):
   title = models.CharField(max_length=200)
   content = CKEditor5Field(
       'Content',
       config_name='default',
       blank=True,
       null=True
   )

With this:

• The editor appears automatically in the Django admin
• The HTML is saved exactly as you edit it
• Images are correctly associated

With this, we can access all the images uploaded through the FileField fields and those uploaded in CKEditor.

And in this simple way, you can already have a fully functional editor, both regarding HTML and the image upload part in Django. It couldn't be easier.

It is being used directly in the admin and is fully functional: you write, upload images, save, and that's it.

Image upload with CKEditor in Django

One of the biggest fears when using CKEditor is:

“Does it really upload the images or does something break?”

The answer is: yes, it works, as long as you have MEDIA_ROOT and MEDIA_URL correctly configured.

The images:

• Are saved in /media/images/
• Are served correctly from Django
• Work just like any FileField

You save the content, right-click on the image, open image… and there it is.

Common problems and solutions

• ❌ The editor does not appear in the admin
  • Check that django_ckeditor_5 is in INSTALLED_APPS
  • Restart the server
• ❌ Images do not load
  • Verify MEDIA_URL and MEDIA_ROOT
  • Make sure to serve media in urls.py
• ❌ Confusion between static and media
  • static → CSS, JS
  • media → files uploaded by users (CKEditor included)

This point causes many errors (often seen in forums), but with the correct configuration, there is no mystery.

Conclusion

Integrating CKEditor 5 in Django is much simpler than it seems. With django-ckeditor-5, a clear media configuration, and a couple of lines in your models, you have a complete, modern HTML editor with image support.

I am using it in the Django admin normally, without strange configurations or file upload problems.

It couldn't be easier.

Frequently Asked Questions about CKEditor and Django

• What is the difference between django-ckeditor and django-ckeditor-5?
  • django-ckeditor uses CKEditor 4 (obsolete).
  • django-ckeditor-5 uses CKEditor 5, which is the current and recommended version.
• Does CKEditor work well in the Django admin?
  • Yes. It is one of the most common uses and it works perfectly.
• Where are the images saved?
  • In the directory defined by MEDIA_ROOT, normally /media/images/.
• Can I use CKEditor outside the admin?
  • Yes, you can also use it in custom forms.
• Is it safe to use CKEditor with HTML?
  • Yes, as long as you control which users can edit content and how you render it.