django-taggit Documentation

In a standard django-taggit setup, tags are stored in the Tag model located in taggit.models. You can retrieve all tags by querying this model directly.

If you are using a custom model implementation (for example, if your models derive from a custom ItemBase), you should query your specific custom tag model instead.

If you save a ModelForm using commit=False, the tags (which are managed via a many-to-many relationship) will not be saved automatically. You must explicitly call form.save_m2m() after saving the instance to ensure the tags are persisted to the database.

if request.method == "POST":
    form = MyFormClass(request.POST)
    if form.is_valid():
        obj = form.save(commit=False)
        obj.user = request.user
        obj.save()
        # Without this next line the tags won't be saved.
        form.save_m2m()

The Taggit admin app supports merging multiple tags into a single new tag. Follow these steps:

1. Navigate to the Tags page within the Taggit app in the Django admin.
2. Select the checkboxes for the tags you wish to merge.
3. Select Merge selected tags from the dropdown action list and click Go.
4. On the following page, enter the name of the new tag you want to use as the replacement.
5. Click Merge Tags.
6. You will be redirected back to the tag list, and all instances of the selected tags will have been replaced by the new tag.

You cannot include a TaggableManager directly in ModelAdmin.list_display because it will raise an AttributeError: '_TaggableManager' object has no attribute 'name' and cause performance issues due to excessive queries.

To display tags in the list view, define a custom method on your ModelAdmin to format the tags as a string and override get_queryset to use prefetch_related('tags') to optimize database performance.

class MyModelAdmin(admin.ModelAdmin):
    list_display = ['tag_list']

    def get_queryset(self, request):
        return super().get_queryset(request).prefetch_related('tags')

    def tag_list(self, obj):
        return u", ".join(o.name for o in obj.tags.all())

You can use standard Django ORM filtering to find models associated with specific tags.

• Filter by name: Use tags__name__in=[...].
• Filter by slug: Use tags__slug__in=[...].
• Custom Tag Models: If using a custom Tag model, you can filter on any fields present in that model.

Note on Duplicates: When filtering by multiple tags, relational databases may return duplicate model instances. Use .distinct() on your QuerySet to ensure unique results.

>>> # Filter by name
>>> Food.objects.filter(tags__name__in=["delicious"])
[<Food: apple>, <Food: pear>, <Food: plum>]

>>> # Filter by multiple tags and avoid duplicates
>>> Food.objects.filter(tags__name__in=["delicious", "red"]).distinct()
[<Food: apple>]

If you want to use a real ForeignKey instead of a GenericForeignKey (for better performance or referential integrity), create an intermediary model that subclasses taggit.models.TaggedItemBase. This model must include a field named content_object pointing to your model. Pass this model to the through argument of TaggableManager.

Note: If you are using custom models, you must remove 'taggit' from your INSTALLED_APPS in settings.py to prevent the default models from being created.

from django.db import models
from taggit.managers import TaggableManager
from taggit.models import TaggedItemBase


class TaggedFood(TaggedItemBase):
    content_object = models.ForeignKey('Food', on_delete=models.CASCADE)

class Food(models.Model):
    # ... fields here

    tags = TaggableManager(through=TaggedFood)

To use django-taggit, install the package via pip, add it to your Django INSTALLED_APPS, and run migrations.

1. Install with pip: pip install django-taggit
2. Add 'taggit' to your INSTALLED_APPS in your Django settings.
3. Run ./manage.py migrate to create the necessary database tables.

$ pip install django-taggit

The default GenericForeignKey assumes integer primary keys. If your model uses a non-integer primary key (like a CharField), your intermediary model must subclass taggit.models.CommonGenericTaggedItemBase and include an object_id field matching the type of your primary key.

from django.db import models
from taggit.managers import TaggableManager
from taggit.models import CommonGenericTaggedItemBase, TaggedItemBase


class GenericStringTaggedItem(CommonGenericTaggedItemBase, TaggedItemBase):
    object_id = models.CharField(max_length=50, verbose_name=_('Object id'), db_index=True)


class Food(models.Model):
    food_id = models.CharField(primary_key=True)
    # ... fields here

    tags = TaggableManager(through=GenericStringTaggedItem)