When should I use a custom Manager versus a custom QuerySet in Django?

I kept reteaching myself what is a Manager vs a QuerySet so, I thought I better write here, so make it easier next time I wonder.

A Manager is the class that is attached to your model and returns a QuerySet instance, objects being the default manager. Most manager methods, ex. all(), filter() return queryset instances.

In more detail, when you do YourModel.objects.filter(..) you get a queryset instance. When you want to filter it again, you can chain another .filter(..) method only because it is also available on the QuerySet class too. That is what you want.. have your methods on both the manager and the queryset it returns.

If filter was not also a manager method, you would have to do YourModel.objects.all() to get the queryset, and then add the filter method(s) from there.

To make things easy, Django defines a as_manager() method on the QuerySet class which turns it into a, well.., a manager [docs]. Therefore, you define all your custom methods on your queryset, and turn it into a manager, and attach to your model, so you can call it the first time (as a manager method) and chain it as many times as you want (as queryset methods).

Writing this answer, I wondered if there are any manager methods shipped with Django that aren't queryset methods, and the first that came to my mind was the get_or_create method since it does not seem to need a queryset. But guess what? that also turned out to be defined on the QuerySet class.

Long story short, you almost always want to write QuerySet methods and have them on the manager too via the as_manager().

Mainly to allow for easy composition of queries. Generally if you want to be able perform some operation on an existing queryset in a chain of queryset calls you can use a QuerySet.

For example, say you have an Image model that has a width, height fields:

class Image(models.Model):
    width = ...  # Width in pixels
    height = ... # Height in pixels

you could write some custom QuerySet methods:

class ImageQuerySet(models.QuerySet): 
    def landscapes(self):
        return self.filter(width__gte=models.F('height'))

    def portraits(self):
        return self.filter(width__lte=models.F('height'))

    def small(self):
        return self.filter(width__lte=1200)

    def large(self):
        return self.filter(width__gte=1200)

class ImageManager(models.Manager):
    def get_queryset(self):
        return ImageQuerySet(self.model, using=self._db)

now you can easily create dynamic querysets:

Image.objects.all().portraits().small()
Image.objects.all().large().portraits()

Logically, these functions should be concerned primarily with partitioning or redefining of existing querysets of the queryset's model. For situations where you aren't operating on existing querysets, you don't want to return a queryset at all, or you might have to perform some related logic that doesn't involve this particular model, than a model manager it better suited.