dynamodb-json is a Python utility library designed to simplify the process of converting Python objects to and from the specific JSON format used by Amazon DynamoDB. It handles the marshalling and unmarshalling of various Python data types, including decimals and datetimes, into the DynamoDB-compatible JSON structure. The current version is 1.4.2 and it maintains an active release cadence, with recent updates focusing on compatibility and bug fixes.
Install & Compatibility
Where this runs
tested against v1.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.770s · 51.7MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 3.9s · import 0.706s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
The primary functionality is exposed via the 'json_util' module, which is commonly aliased as 'json' for consistency with Python's standard json library.
from dynamodb_json import json_util as json
This quickstart demonstrates how to use `dynamodb-json` to convert a standard Python dictionary containing various data types (including `datetime` and `Decimal`) into the DynamoDB-specific JSON format (`dumps`) and then convert a DynamoDB JSON string back into a Python dictionary (`loads`). This is crucial for interacting with the AWS DynamoDB API which expects this specific format.
import os
from datetime import datetime
from decimal import Decimal
from dynamodb_json import json_util as json
# Example Python object with various data types
python_object = {
"Id": 123,
"Name": "Example Item",
"IsActive": True,
"Price": Decimal('99.99'), # DynamoDB expects Decimal for numbers
"CreatedAt": datetime.now(),
"Tags": ["aws", "python", "json"],
"Details": {
"Key": "Value",
"Number": 456
}
}
# 1. Marshal Python object to DynamoDB JSON format
dynamodb_json_format = json.dumps(python_object)
print("DynamoDB JSON Format:")
print(dynamodb_json_format)
# Example DynamoDB JSON string (as if received from DynamoDB)
# Note: datetime objects are converted to ISO 8601 strings during dumps
# and then parsed back to datetime during loads if possible.
# Decimals are preserved.
db_json_string = '{"Id": {"N": "123"}, "Name": {"S": "Example Item"}, "IsActive": {"BOOL": true}, "Price": {"N": "99.99"}, "CreatedAt": {"S": "2026-04-10T18:54:00.000000"}, "Tags": {"L": [{"S": "aws"}, {"S": "python"}, {"S": "json"}]}, "Details": {"M": {"Key": {"S": "Value"}, "Number": {"N": "456"}}}}'
# 2. Unmarshal DynamoDB JSON format back to Python object
python_object_from_db = json.loads(db_json_string)
print("\nPython Object from DynamoDB JSON:")
print(python_object_from_db)
print(f"Type of Price: {type(python_object_from_db['Price'])}")
print(f"Type of CreatedAt: {type(python_object_from_db['CreatedAt'])}")
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.