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.95 runs
installs and imports cleanly · install 0.0s · import 0.760s · 52.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.704s · 53MB
51MB installed
● package 51MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
json_util
✓ from dynamodb_json import json_util as json
✗ import dynamodb_json
The primary functionality is exposed via the 'json_util' module, which is commonly aliased as 'json' for consistency with Python's standard json library.
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'])}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dynamodb-json'
The `dynamodb-json` library is not installed in the Python environment.
fixInstall the library using pip: `pip install dynamodb-json`
TypeError: Object of type 'Decimal' is not JSON serializable
DynamoDB often uses Decimal types for numbers, but Python's standard `json` module cannot serialize `Decimal` objects. This error occurs when attempting to use `json.dumps()` instead of `dynamodb_json.json_util.dumps()` on data containing Decimal objects.
fixUse the `dumps` function from `dynamodb_json.json_util` to correctly serialize Decimal objects: `from dynamodb_json import json_util as json; dynamodb_json = json.dumps(my_data)`
TypeError: Object of type Binary is not JSON serializable
When retrieving items from DynamoDB using `boto3.resource`, binary data (DynamoDB 'B' type) is often represented as a `Binary` object, which the standard Python `json` module cannot serialize. This error occurs when using `json.dumps()` instead of `dynamodb_json.json_util.dumps()` on data containing Binary objects.
fixUse the `dumps` function from `dynamodb_json.json_util` to correctly serialize Binary objects: `from dynamodb_json import json_util as json; dynamodb_json = json.dumps(my_data)`
AttributeError: module 'dynamodb_json' has no attribute 'dumps'
The `dumps` and `loads` functions are part of the `json_util` submodule within `dynamodb_json`, not directly under the `dynamodb_json` package itself. This error occurs if a developer tries to call `dynamodb_json.dumps()` after importing `import dynamodb_json` rather than `from dynamodb_json import json_util` or `from dynamodb_json import json_util as json`.
fixImport the `json_util` submodule correctly: `from dynamodb_json import json_util as json` and then use `json.dumps()` or `json.loads()`.
Upgrade
Version history
1.4.2latest on PyPI · released May 18, 2024
Audit
Dependencies
No dependency data recorded yet.