DynamoDB Batch Write in Python (boto3 batch_writer)

The idiomatic way to bulk-write DynamoDB items in Python is boto3's batch_writer() context manager: it buffers your puts and deletes, sends them as BatchWriteItem calls of up to 25, and automatically resends unprocessed items — the retry loop every other language writes by hand.

Code

import boto3

dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table("Music")

songs = [
    {"Artist": "Arturo Sandoval", "SongTitle": "Cubano Chant", "AlbumTitle": "Danzon", "Year": 1994},
    {"Artist": "Arturo Sandoval", "SongTitle": "A Mis Abuelos", "AlbumTitle": "Danzon", "Year": 1994},
    {"Artist": "Arturo Sandoval", "SongTitle": "Groovin' High", "AlbumTitle": "Swingin'", "Year": 1996},
]

with table.batch_writer() as batch:
    for song in songs:
        batch.put_item(Item=song)
    batch.delete_item(Key={"Artist": "Ella Fitzgerald", "SongTitle": "Misty"})

print(f"Wrote {len(songs)} songs")

Explanation

• batch_writer() — per the boto3 docs, the handle "will automatically handle buffering and sending items in batches", and "will also automatically handle any unprocessed items and resend them as needed". Exiting the with block flushes whatever is still buffered.
• Plain Python values — this is the resource API: no DynamoDB JSON, numbers as int/Decimal. Each put_item item must include the table's full primary key; delete_item takes just the key.
• Duplicate keys — a raw BatchWriteItem call rejects two writes to the same key. If your source data can repeat keys, construct the writer as table.batch_writer(overwrite_by_pkeys=["Artist", "SongTitle"]) — it deduplicates the buffer, keeping the last write per key.
• The same service limits apply underneath: 25 writes per request, 400 KB per item, 16 MB per request. batch_writer handles the chunking; it can't lift the per-item cap.
• No updates, no conditions — BatchWriteItem cannot express UpdateItem or a ConditionExpression; a put on an existing key silently replaces the item. Need all-or-nothing or conditional writes? Use TransactWriteItems.
• Going through the low-level client instead (client.batch_write_item)? Then UnprocessedItems is yours to drain — loop with exponential backoff exactly like the Node.js example.

Do it visually

Checking your items before a bulk load? The item size calculator validates each item against the 400 KB cap, and the DynamoDB Expression Builder copies runnable boto3 code for the follow-up reads and writes.

To bulk-add, edit, and delete items in a GUI — CSV/JSON import included — download DynoTable.

Related examples

• DynamoDB BatchWriteItem in Node.js — the manual retry loop batch_writer hides.
• DynamoDB BatchWriteItem with the AWS CLI — the same batch write from the shell.
• DynamoDB PutItem in Python — the single-item write this batches.
• Batch operations in DynamoDB — limits, partial failure, and when batching pays off.
• "Too many items requested for the BatchWriteItem call" — more than 25 put/delete requests in one batch.
• "Provided list of item keys contains duplicates" — two requests touching the same key in one batch.

References

• Amazon DynamoDB guide (batch_writer) — Boto3 documentation
• BatchWriteItem — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.