Django Tag Me

Simple, flexible tagging for Django.

Add tags to any Django model field -- with a polished widget, per-user tag customization, and automatic resilience to model renames.

Features

• Easy setup -- Add TagMeCharField to your model and go
• Beautiful widget -- Searchable dropdown with tag pills, powered by Alpine.js
• User tags -- Each user gets their own customizable tag set per field
• System tags -- Define default tags available to all users
• Tag synchronization -- Keep tags in sync across related models
• Model rename resilient -- FK-based lookups with automatic orphan detection and repair
• CLI diagnostics -- Health checks, orphan repair, and built-in troubleshooting via tag_me command
• Structured logging -- Observability via structlog for production monitoring
• Form integration -- Drop-in mixin for your model forms
• Template tags -- Display tags as styled pills

Quick Example

# models.py
from tag_me.models import TagMeCharField

class Article(models.Model):
    tags = TagMeCharField(blank=True)
    category = TagMeCharField(choices=CategoryChoices.choices, system_tag=True)

# forms.py
from tag_me.forms import TagMeModelFormMixin

class ArticleForm(TagMeModelFormMixin, forms.ModelForm):
    class Meta:
        model = Article
        fields = ["tags", "category"]

See the Quickstart for the full setup including templates and frontend requirements.

Widget Preview

Dropdown with tag options

Search and filter tags

Model Rename Resilience

Rename your Django models without breaking tags. Tag-me uses ContentType foreign keys instead of model name strings, and automatically detects and merges orphaned records during migration.

# Rename your model, then:
python manage.py makemigrations   # answer "yes" to rename prompt
python manage.py migrate          # tag-me handles the rest

# Verify everything is clean:
python manage.py tag_me check

See How to Upgrade to FK Lookup for details on the FK-based system.

Management Command

Tag-me includes a CLI for diagnostics and administration:

python manage.py tag_me populate              # create/update tags
python manage.py tag_me check                 # data integrity audit
python manage.py tag_me fix-orphans --dry-run # preview orphan repair
python manage.py tag_me help                  # built-in documentation

Tag population runs automatically after every migrate. The CLI exists for diagnostics, manual repair, and single-user operations.

See How to Use the Tag-me CLI for the full guide.

Installation

pip install django-tag-me

See the documentation for setup and usage instructions.

Links

• Documentation
• Source Code
• Issue Tracker

Credits

• Dropdown interface adapted from alpinejs-multiselect
• Built with Django Cookiecutter