related_name in Django

related_name is the name used for reverse access from a related model back to its parent.

Without related_name

class Task(models.Model):
    project = models.ForeignKey(Project, on_delete=models.CASCADE)

# Reverse access — Django auto-generates the name: <model>_set
project = Project.objects.get(pk=1)
project.task_set.all()  # all tasks for the project

With related_name

class Task(models.Model):
    project = models.ForeignKey(
        Project,
        on_delete=models.CASCADE,
        related_name='tasks',  # project.tasks instead of project.task_set
    )

project.tasks.all()
project.tasks.filter(status='done')
project.tasks.count()

Example with Multiple ForeignKeys to the Same Model

class Task(models.Model):
    owner = models.ForeignKey(
        User,
        on_delete=models.CASCADE,
        related_name='owned_tasks',    # user.owned_tasks.all()
    )
    assignee = models.ForeignKey(
        User,
        on_delete=models.SET_NULL,
        null=True,
        blank=True,
        related_name='assigned_tasks', # user.assigned_tasks.all()
    )

Without related_name Django will raise an error: name clash.

related_name=’+’ — Disable Reverse Access

created_by = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name='+',  # no reverse access
)

In a Template

{% for task in project.tasks.all %}
  <li>{{ task.title }}</li>
{% endfor %}

In a DRF Serializer

class ProjectSerializer(serializers.ModelSerializer):
    tasks = TaskSerializer(many=True, read_only=True)  # via related_name

    class Meta:
        model = Project
        fields = ['id', 'name', 'tasks']