Tag Models

Tags are stored in tag models which subclass tagulous.models.TagModel, and use a tagulous.models.TagModelManager. A tag model can either be generated automatically, or you can create a custom model.

Tags in tag models can be protected from automatic deletion when they are not referred to. Initial tags must be loaded using the initial_tags command.

Tag model classes


A TagModel subclass has the following fields and methods:


A CharField containing the name (string value) of the tag.

Must be unique.


A unique SlugField, generated automatically from the name when first saved.

If unidecode is installed, Tagulous will use it to make a best-guess conversion of non-ascii characters to something similar in ascii which will be safe for a slug field. If unidecode is not installed, Tagulous will strip diacritical marks from extended ascii characters, but then just convert any remaining non-ascii characters to underscores. In most cases either option will be adequate for European languages, but if your tags frequently contain non-European characters you'll have less slug clashes if you use unidecode.


An IntegerField holding the number of times this tag is in use.


A BooleanField indicating whether this tag should be protected from deletion when the count reaches 0.

It also has several methods primarily for internal use, but some may be useful:


Return a list of instances of other models which refer to this tag; see the API for more details


In case you're doing something weird which causes the count to get out of sync, call this to update the count, and delete the tag if appropriate.


Merge the specified tags into this tag.

tags can be a queryset, list of tags or tag names, or a tag string.


A TagModelManager is the standard manager for a tagulous.models.TagModel; it is a subclass of the normal Django model manager, but its queries return a tagulous.models.TagModelQuerySet instead.

It also provides the following additional methods:


Calls the normal filter(...) method, but then adds on any initial tags which may be missing.

weight(min=1, max=6)

Annotates a weight field to the tags. This is a weighted count between the specified min and max, which default to TAGULOUS_WEIGHT_MIN and TAGULOUS_WEIGHT_MAX (see Settings).

This can be used to generate tag clouds, for example.


This is returned by the tagulous.models.TagModelManager; it is a subclass of the normal Django QuerySet class, but implements the same additional methods as the TagModelManager.

Custom Tag Models

A custom tag model should subclass tagulous.models.TagModel, so that Tagulous can find the fields and methods it expects, and so it uses the appropriate tag model manager and queryset.

A custom tag model is a normal model in every other way, except it can have a TagMeta class to define default options for the class.

There is an example which illustrates how to create a custom tag model.

If you want to use tag trees, you will need to subclass tagulous.models.TagTreeModel instead. The only difference is that there will be extra fields on the model - see Tag Trees for more details.


The TagMeta class is a container for tag options, to be used when creating a custom tag model.

Set any Model Options as class properties. When the model is created by Python, the options will be available on the tag model class and tag fields which use it as tag_options.

Tag fields will not be able to override these options, and SingleTagField fields will ignore max_count.

If tree is specified, it must be appropriate for the base class of the tag model, eg if tree=True the tag model must subclass tagulous.models.TagTreeModel - but if it is not provided it will be set to the correct value.

TagMeta can be inherited, so it can be set on abstract models. Options in the TagMeta of a parent model can be overridden by options in the TagMeta of a child model.


import tagulous
class MyTagModel(tagulous.models.TagModel):
    class TagMeta:
        initial = 'judo, karate'

Protected tags

The tag model keeps a count of how many times each tag is referenced. When the tag count reaches 0, the tag will be deleted unless its protected field is True, or the protect_all option has been used.

Loading initial tags

Initial tags must be loaded using the initial_tags management command. You can either load all initial tags in your site by not passing in any arguments, or specify an app, model or field to load:

python manage.py initial_tags [<app_name>[.<model_name>[.<field_name>]]]
  • Tags which are new will be created
  • Tags which have been deleted will be recreated
  • Tags which exist will be untouched