django-taggit

Warnings

• breaking As of `django-taggit` 6.1.0, Python 3.8 is no longer supported; Python 3.9+ is now required. While PyPI metadata may still show `>=3.8`, the official documentation and changelog confirm the updated requirement.
  Fix: Ensure your project uses Python 3.9 or newer. Downgrade `django-taggit` to a 5.x version if Python 3.8 support is critical.
• breaking In `django-taggit` 6.0.0, the default ordering of tag items on instances changed to be by primary key (effectively creation date). Previously, tag items were not explicitly ordered, which could lead to inconsistent results.
  Fix: If you relied on the previous unordered behavior or a specific custom ordering, you can explicitly set `ordering=[]` on your `TaggableManager` instance: `tags = TaggableManager(ordering=[])`.
• gotcha Tag lookups are case-sensitive by default. Tags like 'Python' and 'python' will be treated as distinct tags.
  Fix: To enable case-insensitive tag lookups, add `TAGGIT_CASE_INSENSITIVE = True` to your Django `settings.py` file. This setting is `False` by default.
• gotcha When using `django-taggit` with Django REST Framework, the `TaggableManager` field does not behave like a simple list for serialization. Direct `ModelSerializer` usage for tags might lead to exceptions.
  Fix: You often need to implement custom serializer fields or methods (e.g., `TagListSerializerField` from `taggit.serializers` or custom `serializers.SlugRelatedField`) to correctly handle tag input and output with DRF.
• breaking In `django-taggit` 5.0.0, there was an issue where package metadata incorrectly stated `Django >=3.2`. This could lead to `pip` automatically upgrading Django to an incompatible version (e.g., Django 4.0 for a Django 2.2 project) upon `django-taggit` installation if version bounds were not specified.
  Fix: When installing, always pin `django-taggit` to a compatible version for your Django installation (e.g., `pip install 'django-taggit<5'` for older Django) or ensure `Django` itself is pinned to avoid unexpected upgrades. This was fixed in `5.0.1`.
• gotcha If you wish to use custom Tag or Through models, you must remove `'taggit'` from your `INSTALLED_APPS` setting. Including it will create `django-taggit`'s default models, which might conflict or be redundant.
  Fix: Remove `'taggit'` from `INSTALLED_APPS` if you are providing your own custom tag models and ensure your custom models are correctly configured according to the 'Customizing taggit' documentation.

Install

• pip install django-taggit Install latest version

Imports

• TaggableManager

  from taggit.managers import TaggableManager

  Used to add a tag field to a Django model.
• Tag

  from taggit.models import Tag

  Used to directly interact with the Tag model, e.g., for querying all tags.

Quickstart

To quickly integrate `django-taggit`, install it, add 'taggit' to your `INSTALLED_APPS`, run migrations, and then add a `TaggableManager` field to your Django model. This example demonstrates basic model creation, tag assignment, filtering, and tag removal.

import os
import django
from django.conf import settings
from django.db import models

settings.configure(
    INSTALLED_APPS=[
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'taggit',
    ],
    DATABASES={
        'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}
    },
    SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-that-should-be-changed'),
    DEFAULT_AUTO_FIELD='django.db.models.BigAutoField',
)
django.setup()

from taggit.managers import TaggableManager

class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    tags = TaggableManager()

    def __str__(self):
        return self.title

# --- Example Usage ---

# After migrations (run `python manage.py migrate` in a real project):
# from django.core.management import call_command
# call_command('migrate', interactive=False)

# Create a post
post1 = Post.objects.create(title='My First Post', content='Content goes here.')
post1.tags.add('python', 'django', 'tutorial')

post2 = Post.objects.create(title='Another Post', content='More content.')
post2.tags.add('python', 'web-dev')

print(f"Post 1 tags: {list(post1.tags.names())}")
print(f"Posts tagged with 'python': {Post.objects.filter(tags__name__in=['python']).count()}")
print(f"All tags: {list(TaggableManager().all_tags().names())}")

# Remove a tag
post1.tags.remove('tutorial')
print(f"Post 1 tags after removal: {list(post1.tags.names())}")