django CMS Link Plugin

5.1.1 verified Sat May 09 auth: no python

Adds a link plugin to django CMS, allowing editors to create links to internal pages, external URLs, mailto, telephone, and anchors. Current version 5.1.1, requires Python >=3.9, follows django CMS's release cadence.

pip install djangocms-link

Common errors

error ImportError: cannot import name 'LinkPlugin' from 'djangocms_link.cms_plugins' ↓

cause The correct model is in djangocms_link.models, not cms_plugins.

fix

Change import to: from djangocms_link.models import LinkPlugin

error django.core.exceptions.ImproperlyConfigured: Application labels aren't unique, duplicates: djangocms_link ↓

cause The app is registered twice, often due to duplicate entries in INSTALLED_APPS or importing the app config multiple times.

fix

Ensure 'djangocms_link' appears only once in INSTALLED_APPS and avoid importing the AppConfig manually.

error AttributeError: 'NoneType' object has no attribute 'pk' ↓

cause The link's internal page reference is null; plugin may have been saved without a target.

fix

Delete and recreate the plugin, ensuring a valid target is selected. For existing data, set a default or handle None in the template.

error OperationalError: no such table: djangocms_link_link ↓

cause Migration not run after adding the app.

fix

Run: python manage.py migrate djangocms_link

Warnings

breaking Version 5.0 introduced a new Link widget and JSON endpoint. If you have custom templates or subclass the plugin, you may need to adapt to the new widget implementation. ↓

fix Review the new widget and endpoint; update any custom code that relied on the old form field or internal URL generation.

deprecated The `cms_plugins.LinkPlugin` import is deprecated. Use `djangocms_link.models.LinkPlugin` instead. ↓

fix Change import to from djangocms_link.models import LinkPlugin.

gotcha Plugin fails silently on uninstalled apps or models (e.g., missing django-cms). Ensure django CMS is properly installed and in INSTALLED_APPS. ↓

fix Verify django CMS installation: 'django-cms' in INSTALLED_APPS and run migrations.

gotcha The 'to_url' template tag now accepts model objects as parameters (since 5.1.0). Passing unsupported types will raise errors. ↓

fix Ensure you pass a valid model instance (e.g., Page) or string URL to the tag.

Imports

LinkPlugin

wrong

from djangocms_link.cms_plugins import LinkPlugin

correct

from djangocms_link.models import LinkPlugin

The model is the canonical source; the cms_plugins module does not export it.

get_link

from djangocms_link.templatetags.djangocms_link_tags import get_link

Quickstart

Add djangocms_link to INSTALLED_APPS, then migrate and collect static files.

INSTALLED_APPS = [
    ...
    'djangocms_link',
]

# Then run:
# python manage.py migrate djangocms_link
# python manage.py collectstatic