Install & Compatibility
Where this runs
tested against v1.4.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.5s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSONField
✓ from jsonfield.fields import JSONField
✗ from jsonfield import JSONField
This quickstart demonstrates how to define a model using `django-jsonfield.JSONField`, create instances with JSON data, update the data, and perform queries directly on the JSON fields. It includes a minimal Django setup for standalone execution.
import os
import django
from django.conf import settings
from django.db import models
from jsonfield.fields import JSONField # Correct import
# Minimal Django setup for standalone script
if not settings.configured:
settings.configure(
DEBUG=True,
INSTALLED_APPS=[
'myapp', # A dummy app for models
],
DATABASES={
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': ':memory:',
}
},
)
django.setup()
class MyModel(models.Model):
name = models.CharField(max_length=255)
metadata = JSONField(default=dict) # Use default=dict for easier creation
class Meta:
app_label = 'myapp' # Required when models are not in a formal app dir
def __str__(self):
return f"{self.name} (Metadata: {self.metadata})";
# Simulate migrations for the quickstart
try:
from django.core.management import call_command
from io import StringIO
out = StringIO()
call_command('makemigrations', 'myapp', stdout=out, stderr=out, verbosity=0)
call_command('migrate', 'myapp', stdout=out, stderr=out, verbosity=0)
except Exception as e:
print(f"Warning: Could not run Django migrations simulation: {e}. Attempting manual schema creation.")
# Fallback for environments where call_command is tricky
with django.db.connection.schema_editor() as schema_editor:
schema_editor.create_model(MyModel)
# Create an instance
instance = MyModel.objects.create(
name="Product A",
metadata={'sku': 'P-001', 'dimensions': {'width': 10, 'height': 20}}
)
print(f"Created: {instance}")
# Update JSON data
instance.metadata['status'] = 'available'
instance.metadata['dimensions']['depth'] = 5
instance.save()
print(f"Updated: {instance}")
# Retrieve and access JSON data
retrieved = MyModel.objects.get(name="Product A")
print(f"Retrieved SKU: {retrieved.metadata['sku']}")
# Query JSON data directly (supported by django-jsonfield)
products_with_sku = MyModel.objects.filter(metadata__sku='P-001')
print(f"Found {products_with_sku.count()} product(s) with SKU P-001.")
products_wide = MyModel.objects.filter(metadata__dimensions__width__gt=5)
print(f"Found {products_wide.count()} product(s) with width > 5.")
Debug
Known issues
gotchaDjango 3.1 and newer versions include a built-in `JSONField` (`from django.db.models import JSONField`). `django-jsonfield` provides a distinct implementation for older Django versions (2.2-3.0) or specific features. Be careful not to mix them, as behavior and query methods may differ. If using Django 3.1+, consider the built-in field first unless you have a specific reason for this library.fixFor new projects on Django 3.1+, prefer `from django.db.models import JSONField`. If upgrading an existing project using `django-jsonfield` to Django 3.1+, plan a careful migration path, potentially involving data migrations, if you wish to switch to the built-in field.
affects: All versions of django-jsonfield and Django 3.1+
breakingThe `db_index` parameter was removed from `JSONField` in version 1.0. This parameter was never actually supported by PostgreSQL for JSONB columns and was silently ignored. Using it with `django-jsonfield>=1.0` will raise a `TypeError`.fixRemove `db_index=True` (or `False`) from your `JSONField` definitions in your Django models when upgrading to version 1.0 or later.
affects: 1.0 and newer
gotchaThe Python package name for the `JSONField` class is `jsonfield`, not `django_jsonfield`. Attempting to import from `django_jsonfield.fields` will result in an `ImportError`.fixAlways use `from jsonfield.fields import JSONField` for correct import.
affects: All versions
Upgrade
Version history
1.4.1latest on PyPI · released Oct 28, 2020
Audit
Dependencies
DjangorequiredRequired for integration with Django models.