Install & Compatibility
Where this runs
tested against v3.2.0 · 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.738s · 66.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.662s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSONField
✓ from jsonfield import JSONField
✗ from django.contrib.postgres.fields import JSONField
This package's JSONField is distinct from Django's native JSONField (located at `django.db.models.JSONField` or older `django.contrib.postgres.fields.JSONField`).
Define a model with `jsonfield.JSONField`. It's recommended to use a callable for mutable defaults (like `dict` or `list`) to avoid shared state issues.
from django.db import models
from jsonfield import JSONField
class MyModel(models.Model):
name = models.CharField(max_length=100)
data = JSONField(default=dict) # Use a callable for mutable defaults
# Example usage:
# obj = MyModel.objects.create(name='Example', data={'key': 'value', 'number': 123})
# print(obj.data['key'])
Debug
Known issues
deprecatedThe `jsonfield` package is deprecated. Django 3.1 and newer versions provide a native `django.db.models.JSONField` that is recommended for all new projects and migrations. The native field offers better database-agnostic support and enhanced querying capabilities, especially with PostgreSQL's JSONB.fixMigrate to `django.db.models.JSONField`. For existing projects, this generally involves swapping the field class in your models and running `makemigrations` and `migrate`. Complex data structures or older migrations might require manual data migration strategies.
affects: All versions of `jsonfield` when used with Django 3.1+.
breakingVersion 3.0.0 introduced significant breaking changes, including dropping support for Django versions older than 2.0 and Python versions older than 3.5. It also reworked field serialization/deserialization, moved form fields (e.g., `JSONFormField` was renamed to `forms.JSONField` and moved), and removed South migration support.fixBefore upgrading to `jsonfield` 3.0.0+, ensure your Django project is on version 2.0+ and Python on 3.5+. Carefully review the `CHANGES.rst` for `v3.0.0` on the GitHub repository to adapt to changes in import paths for form fields and serialization logic.
affects: 3.0.0 and later.
breakingVersion 1.0.0 (and related pre-1.0.0 releases) introduced a breaking change by removing direct native PostgreSQL JSON data type support. If your project relied on PostgreSQL's native JSON features with `jsonfield` versions prior to 1.0.0, upgrading to 1.0.0+ can be a breaking change as data might subsequently be stored as plain text.fixConsult the specific migration guidance for PostgreSQL users upgrading from `<1.0.0`, particularly `https://github.com/dmkoch/django-jsonfield/issues/57`. For native PostgreSQL JSON features (like JSONB indexing), it is strongly recommended to use Django's built-in `django.db.models.JSONField` instead.
affects: 1.0.0 and later.
gotchaThere are multiple Python packages on PyPI that are named 'jsonfield' or 'django-jsonfield'. This entry specifically refers to the `jsonfield` package (on PyPI, `rpkilby/jsonfield` on GitHub, formerly `bradjasper/django-jsonfield`). Be cautious not to confuse it with other packages, such as `django-jsonfield` (on PyPI, `adamchainz/django-jsonfield` on GitHub).fixAlways verify the correct package is installed and imported by checking `pip show jsonfield` and confirming the source URL matches `https://github.com/rpkilby/jsonfield`.
affects: All versions.
gotchaWhile `jsonfield` stores JSON, its querying capabilities are limited to basic text lookups (e.g., `exact`, `regex`) because values are stored as serialized JSON strings. It is not designed to provide advanced, database-native JSON querying functionalities like those offered by `django.db.models.JSONField` (especially when used with PostgreSQL's JSONB type).fixFor complex querying or leveraging native JSON database features (such as key lookups, containment, or indexing), migrate to `django.db.models.JSONField` and ensure you are using a PostgreSQL database.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonfield'
The 'jsonfield' package is not installed in the Python environment.
fixInstall the package using 'pip install jsonfield'.
AttributeError: module 'jsonfield' has no attribute 'JSONField'
Incorrect import statement; 'JSONField' should be imported directly from 'jsonfield'.
fixUse 'from jsonfield import JSONField' instead of 'import jsonfield'.
ValidationError: ['Enter valid JSON.']
The input provided to the JSONField is not valid JSON.
fixEnsure the input is a properly formatted JSON string, e.g., '{"key": "value"}'. TypeError: the JSON object must be str, bytes or bytearray, not 'dict'
A Python dictionary is being assigned directly to a JSONField, which expects a JSON-encoded string.
fixSerialize the dictionary to a JSON string using 'json.dumps()' before assignment.
django.db.utils.OperationalError: index row requires 8336 bytes, maximum size is 8191
Attempting to create a B-tree index on a JSONField with large data exceeds the maximum index size.
fixAvoid indexing the entire JSONField; instead, create specific indexes on the necessary keys or use a GIN index if supported by the database.
Upgrade
Version history
3.2.0latest on PyPI · released Jul 4, 2025
Audit
Dependencies
DjangorequiredThis is a Django model field and requires a Django project to be used. The `requires_python` is `>=3.10`.