# django-taggit: Adding Tags to Django Models with One Field

> django-taggit is a Python library that adds a tagging field to any Django model in a single line, automatically wiring up admin integration, form widgets, and queryset filtering. It requires Django 5.2 or greater and is maintained under the Jazzband collaborative stewardship model.

**jazzband/django-taggit** — Simple tagging for django

- Repository: https://github.com/jazzband/django-taggit
- Website: https://django-taggit.readthedocs.io
- Stars: 3,448 · Forks: 635
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/jazzband-django-taggit

## What django-taggit Provides and Who It Is For

Tagging is a common requirement: a blog with post categories, a media library with keyword labels, a recipe database with ingredient tags. Implementing it without a library means creating a Tag model, a many-to-many through table, admin configuration, form handling, and custom queryset methods. django-taggit handles all of that with a single manager field.

The library targets Django developers who want to add free-form string tags to one or more models without writing the underlying database schema or API from scratch. The README presents the minimum viable usage in a few lines:

```python
from django.db import models

from taggit.managers import TaggableManager

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

    tags = TaggableManager()
```

With that single field added, the model immediately gains tag management, admin integration, and form support. The README states that tags will show up automatically in forms and the admin.

## The Tag API: Adding, Removing, and Filtering

Once a model includes a TaggableManager, the tag API is available on every instance. The README demonstrates the core operations:

```python
>>> apple = Food.objects.create(name="apple")
>>> apple.tags.add("red", "green", "delicious")
>>> apple.tags.all()
[<Tag: red>, <Tag: green>, <Tag: delicious>]
>>> apple.tags.remove("green")
>>> apple.tags.all()
[<Tag: red>, <Tag: delicious>]
>>> Food.objects.filter(tags__name__in=["red"])
[<Food: apple>, <Food: cherry>]
```

The tags.add() method accepts multiple tag strings in a single call. The filter on tags__name__in works as a standard Django ORM lookup, meaning it composes with other filter conditions and supports chaining. The README shows no special syntax for that queryset path; it uses Django's existing double-underscore field traversal convention.

This API design keeps tagging code close to the Django conventions developers already know. A developer familiar with Django's ORM needs no additional mental model to start filtering by tag.

## Installation and Setup

The README describes a two-step setup process. First, install the package from PyPI:

```bash
pip install django-taggit
```

Then add the application to Django's INSTALLED_APPS setting:

```python
INSTALLED_APPS = [
    ...
    "taggit",
]
```

After that, add TaggableManager to any model and run migrations to create the required database tables. The README specifies that Django 5.2 or greater is required; earlier versions are not supported by the current codebase. The pyproject.toml uses setuptools as the build backend and declares no Python version pins in the available portion, but the full requirements and compatibility matrix are in the documentation at django-taggit.readthedocs.io.

## Jazzband Stewardship and What It Means in Practice

django-taggit is a Jazzband project. Jazzband is a collaborative organization that adopts Python and Django packages whose original maintainers want to share ongoing stewardship. Contributing to a Jazzband project requires agreeing to the Contributor Code of Conduct and following Jazzband's contribution guidelines.

For users, the practical effect is that the package is less likely to go unmaintained when a single author steps back. The Jazzband model distributes commit rights and release responsibility among a group of contributors. The repository is on the master branch, and the last push was on 2026-08-24.

The package is licensed under BSD-3-Clause, which permits use in commercial and proprietary projects. The license does not require publishing source code but does require preserving the copyright notice.

## Limitations: No Built-In Autocomplete, Tag Counts, or Slugification

django-taggit provides the data model and queryset API for tags, but it does not ship autocomplete widgets, tag cloud rendering, or tag count annotations out of the box. A search for related packages returns names like taggit-serializer and django-taggit-autosuggest, which are separate third-party additions rather than features of this library.

The default Tag model stores the tag name as entered. The library does not normalize case or strip whitespace beyond what the database layer does. Tags added as "Red" and "red" could end up as distinct entries depending on the database collation settings. This behavior is a trade-off in favor of simplicity; teams with strict normalization requirements should review the documentation for custom Tag model options.

The README mentions a sample_taggit application in the repository, which serves as a demonstration project, but the README does not walk through it in detail. The full documentation at django-taggit.readthedocs.io is the authoritative reference for customization.

## What the Repository Contains Beyond the Core Package

The repository includes a sample_taggit application under the sample_taggit/ directory, which serves as a working demonstration project. The tests/ directory contains the test suite, and the docs/ directory holds the documentation source for django-taggit.readthedocs.io.

The build configuration uses setuptools with the pyproject.toml specifying setuptools>=64.0 and wheel as build requirements. A tox.ini and requirements/ directory indicate that the test suite is run across multiple Python and Django version combinations. The .pre-commit-config.yaml and .readthedocs.yml files round out the development tooling.

Contributors are governed by both the Jazzband code of conduct and contribution guidelines, which are linked from the README. Issues about usage carry a question tag on GitHub, keeping support questions separate from bug reports and feature requests.

## Comparison with Django's Built-In ManyToManyField

Django's built-in ManyToManyField can implement tagging by pointing to a Tag model the developer writes. That approach gives full control over the Tag schema, the through table, and the admin configuration, but every piece of that is code the developer maintains.

django-taggit ships the Tag model, the through table, the admin configuration, and the manager API as a tested, versioned unit. The cost of that convenience is that the schema is fixed to taggit's structure unless the developer uses the documented customization points. Teams who need a non-standard tag structure should read the customization documentation before committing to django-taggit; teams who need the standard case get a working implementation with two lines of setup code.

The related package django-mptt, which the related searches surface alongside django-taggit, solves a different problem: hierarchical tree structures in the database. It is not a tagging library; it is for parent-child relationships like comment trees or category hierarchies. The two libraries address distinct data modeling needs and can coexist in the same project.

## Conclusion

django-taggit is a good fit for any Django project that needs free-form labels on models and wants those labels to work automatically in the admin, in forms, and in queryset filters. The minimum requirement is Django 5.2, so teams on older versions need to upgrade before adopting it. Before deploying, verify that the default Tag model structure suits the data requirements; the full documentation at django-taggit.readthedocs.io covers customization options that the README does not. The last push was on 2026-08-24.

## FAQ

### What is django-taggit?

django-taggit is a Django library that adds a TaggableManager field to any model, providing tag add, remove, and filter operations along with automatic admin and form integration. It requires Django 5.2 or greater.

### How do I filter Django model instances by tag using django-taggit?

The README shows using a standard Django ORM double-underscore lookup: Food.objects.filter(tags__name__in=["red"]) returns all Food instances that have the tag named "red".

### Does django-taggit work with Django's admin interface automatically?

The README states that tags will show up automatically in forms and the admin once TaggableManager is added to a model. No additional admin configuration code is required for basic tag management.

## Sources

- [Issues](https://github.com/jazzband/django-taggit/issues)
- [jazzband/django-taggit on GitHub](https://github.com/jazzband/django-taggit)
- [License: BSD-3-Clause](https://github.com/jazzband/django-taggit/blob/master/LICENSE)
- [Project website](https://django-taggit.readthedocs.io)
- [README](https://github.com/jazzband/django-taggit/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jazzband-django-taggit