How to Use bulk_create in Django for Fast Database Inserts

Use Django's bulk_create method on a model's manager to insert many objects at once in the database. Create a list of model instances and pass it to bulk_create to save them efficiently with a single query.

Syntax

The bulk_create method is called on a Django model's manager. It takes a list of model instances and inserts them into the database in one query.

• objs: A list of unsaved model instances.
• batch_size (optional): Number of objects to insert per query to avoid large queries.
• ignore_conflicts (optional): If True, ignores conflicts like duplicate keys.

python

Model.objects.bulk_create(objs, batch_size=None, ignore_conflicts=False)

Example

This example shows how to create multiple Book objects and save them all at once using bulk_create. It is faster than saving each object individually.

python

from django.db import models

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=100)

# Create a list of Book instances
books = [
    Book(title='Book One', author='Author A'),
    Book(title='Book Two', author='Author B'),
    Book(title='Book Three', author='Author C'),
]

# Insert all books in one query
Book.objects.bulk_create(books)

# Verify by querying all books
all_books = Book.objects.all()
for book in all_books:
    print(f'{book.title} by {book.author}')

Output

Book One by Author A
Book Two by Author B
Book Three by Author C

Common Pitfalls

Common mistakes when using bulk_create include:

• Not creating model instances before passing to bulk_create. You must pass unsaved model objects, not dictionaries.
• Expecting bulk_create to call save() or trigger signals like pre_save or post_save. It does not.
• Trying to use bulk_create with models that have auto-generated primary keys and expecting the IDs to be set on the objects after insertion (only supported in some databases).
• Not using batch_size when inserting very large lists, which can cause memory or database issues.

python

from django.db import models

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

# Wrong: passing dictionaries instead of model instances
items = [
    {'name': 'Item 1'},
    {'name': 'Item 2'},
]
# This will raise an error
# Item.objects.bulk_create(items)

# Right: create model instances first
items = [Item(name='Item 1'), Item(name='Item 2')]
Item.objects.bulk_create(items)

Quick Reference

Tips for using bulk_create effectively:

• Use bulk_create to insert many objects quickly in one query.
• Pass a list of unsaved model instances, not dictionaries.
• Use batch_size to split large inserts into smaller chunks.
• Signals and save() methods are not called during bulk_create.
• Check database support for returning IDs after bulk insert if you need them.

Key Takeaways

Use bulk_create to insert many model instances efficiently in one database query.

Always pass unsaved model instances, not dictionaries, to bulk_create.

bulk_create does not call save() or trigger model signals.

Use batch_size to avoid very large queries when inserting many objects.

Check your database support if you need primary keys set on objects after bulk_create.