How to Use bulk_update in Django for Efficient Batch Updates

Use Django's bulk_update method to update multiple model instances efficiently in one database query by passing a list of model objects and the fields to update. This method reduces database hits compared to updating each instance individually.

Syntax

The bulk_update method is called on a Django model's manager or queryset. It takes two main arguments: a list of model instances to update and a list of field names to update on those instances.

Example syntax:

Model.objects.bulk_update(objs, fields, batch_size=None)

• objs: List of model instances with updated values.
• fields: List of field names (strings) to update.
• batch_size (optional): Number of objects to update per query for large lists.

python

Model.objects.bulk_update(objs, ['field1', 'field2'], batch_size=100)

Example

This example shows how to update the price field of multiple Product instances efficiently using bulk_update.

python

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=6, decimal_places=2)

# Assume we have some products already saved
products = list(Product.objects.all())

# Increase price by 10 for each product
for product in products:
    product.price += 10

# Update all products in one query
Product.objects.bulk_update(products, ['price'])

# Verify update
updated_prices = list(Product.objects.values_list('price', flat=True))
print(updated_prices)

Output

[updated prices list with each price increased by 10]

Common Pitfalls

• Not specifying the fields list correctly will cause errors or no updates.
• Passing unsaved model instances will raise errors; all objects must have a primary key.
• Changes to fields not listed in fields will not be saved.
• bulk_update does not call save() or trigger signals.

python

from django.db import models

class Item(models.Model):
    name = models.CharField(max_length=50)
    quantity = models.IntegerField()

items = list(Item.objects.all())

# Wrong: forgetting to specify fields
# Item.objects.bulk_update(items)  # Raises TypeError

# Wrong: updating unsaved instance
new_item = Item(name='New', quantity=5)
# Item.objects.bulk_update([new_item], ['quantity'])  # Raises ValueError

# Right way
for item in items:
    item.quantity += 1
Item.objects.bulk_update(items, ['quantity'])

Quick Reference

Parameter	Description
objs	List of model instances to update (must have primary keys)
fields	List of field names (strings) to update on each instance
batch_size	Optional integer to split updates into batches for large lists
Returns	Number of rows matched (not necessarily updated)

Key Takeaways

Use bulk_update to update many model instances in one database query for better performance.

Always provide a list of fields to update; only those fields will be saved.

Ensure all model instances have primary keys before calling bulk_update.

bulk_update does not call save() or trigger signals, so use it when you don't need those.

Use batch_size to control query size when updating large numbers of objects.