Install & Compatibility
Where this runs
tested against v1.0.3 · 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.944s · 43.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.854s · 41MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSONField
✓ from sqlalchemy_jsonfield import JSONField
JSONMutableDict
✓ from sqlalchemy_jsonfield import JSONMutableDict
Required for SQLAlchemy to detect in-place modifications to JSON dictionary data.
This quickstart demonstrates how to define a model with a `JSONField` that uses `JSONMutableDict` for automatic change detection. It shows creating, retrieving, and updating JSON data in-place, with changes being correctly persisted to an in-memory SQLite database.
import sqlalchemy as sa
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from sqlalchemy_jsonfield import JSONField, JSONMutableDict
# Define the base for declarative models
Base = declarative_base()
# Define a model with a JSONField
class Data(Base):
__tablename__ = 'data'
id = sa.Column(sa.Integer, primary_key=True)
# Use JSONField with JSONMutableDict to enable automatic change tracking
json_data = sa.Column(JSONField(JSONMutableDict), default={})
# Setup database engine and session
engine = sa.create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()
try:
# Create a new item
item = Data(json_data={'initial_key': 'initial_value', 'list_data': [1, 2]})
session.add(item)
session.commit()
print(f"Created item ID: {item.id}, Data: {item.json_data}")
# Retrieve the item
retrieved_item = session.query(Data).filter_by(id=item.id).first()
print(f"Retrieved item ID: {retrieved_item.id}, Data: {retrieved_item.json_data}")
# Update the JSON data in-place (changes detected by JSONMutableDict)
retrieved_item.json_data['new_key'] = 'new_value'
retrieved_item.json_data['list_data'].append(3)
session.commit()
print(f"Updated item ID: {retrieved_item.id}, Data: {retrieved_item.json_data}")
# Verify update by re-retrieving
verified_item = session.query(Data).filter_by(id=item.id).first()
print(f"Verified item ID: {verified_item.id}, Data: {verified_item.json_data}")
finally:
session.close()
Debug
Known issues
gotchaFailing to use `JSONMutableDict` will prevent SQLAlchemy from detecting in-place modifications to the JSON data. If you define a `JSONField` as `sa.Column(JSONField(dict))` instead of `sa.Column(JSONField(JSONMutableDict))`, changes like `instance.json_data['key'] = 'value'` will not be saved unless the entire dictionary is reassigned (`instance.json_data = new_dict`).fixAlways use `JSONField(JSONMutableDict)` when you intend to modify the JSON dictionary in-place and have those changes automatically detected and persisted by SQLAlchemy.
affects: <1.0.0
breakingPrior to version 0.7.0, `sqlalchemy-jsonfield` might have implicitly or explicitly relied on the `ujson` library for serialization. From version 0.7.0 onwards, it defaults to Python's standard `json` library and allows specifying a custom JSON library (e.g., `json=ujson`) via the `JSONField` constructor. This change could subtly alter serialization behavior or performance if your application implicitly depended on `ujson`'s characteristics.fixIf your application relied on `ujson` behavior, ensure you explicitly pass `json=ujson` to `JSONField(..., json=ujson)` when initializing your column. Otherwise, be aware that serialization might now use Python's standard `json` module.
affects: <0.7.0 to 0.7.0+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlalchemy_jsonfield'
The `sqlalchemy-jsonfield` library is not installed in the current Python environment or the import statement uses an incorrect package name.
fixInstall the library using `pip install sqlalchemy-jsonfield`.
Changes made to a dictionary within a `sqlalchemy_jsonfield.JSONField` are not saved to the database.
The `JSONField` was not configured with `mutable=True`, which means it doesn't use `JSONMutableDict` for automatic change tracking. Direct modifications to a non-mutable dictionary will not trigger SQLAlchemy's dirty tracking.
fixDeclare the `JSONField` with `mutable=True` (e.g., `data = Column(JSONField(mutable=True))`). If `mutable=False`, you must reassign the entire dictionary to the column to trigger persistence (e.g., `instance.data = {'key': 'new_value', **instance.data}`). TypeError: Object of type <SomeType> is not JSON serializable
The `JSONField` attempts to serialize a Python object (e.g., `datetime`, custom class instance) that the default `json.dumps` function cannot convert into a JSON-compatible string.
fixConvert non-serializable objects into a JSON-serializable format (e.g., string representation for `datetime`) before assigning them to the `JSONField`.
from sqlalchemy.jsonfield import JSONField
The user is attempting to import `JSONField` from the `sqlalchemy` package directly, but `sqlalchemy-jsonfield` is a separate, third-party library with its own top-level package name.
fixThe correct import statement is `from sqlalchemy_jsonfield import JSONField`.
Upgrade
Version history
1.0.3latest on PyPI · released May 11, 2026
Audit
Dependencies
SQLAlchemyrequiredRequired for ORM integration and database interaction