Install & Compatibility
Where this runs
tested against v4.19.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.000s · 66.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.6s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSONField
✓ from django_mysql.models import JSONField
✗ from django_mysql.models import JSONField
To quickly get started with Django-MySQL, first ensure you have a MySQL/MariaDB database configured in your Django settings. Add 'django_mysql' to your `INSTALLED_APPS`. This example demonstrates defining a model with a `django_mysql.models.JSONField` which provides native JSON support for MySQL. After defining your models, run `makemigrations` and `migrate` to apply the database schema changes. Note: For a runnable example, ensure your `settings.py` includes `INSTALLED_APPS` and `DATABASES` configurations, and substitute 'myapp' with the actual name of your Django app containing the model.
import os
from django.conf import settings
from django.apps import apps
if not apps.ready:
settings.configure(
INSTALLED_APPS=[
'django.contrib.auth',
'django.contrib.contenttypes',
'django_mysql',
'myapp' # Assuming your models are in 'myapp'
],
DATABASES={
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'mydatabase',
'USER': os.environ.get('MYSQL_USER', 'root'),
'PASSWORD': os.environ.get('MYSQL_PASSWORD', ''),
'HOST': os.environ.get('MYSQL_HOST', 'localhost'),
'PORT': os.environ.get('MYSQL_PORT', '3306'),
'OPTIONS': {
'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
}
}
},
DEFAULT_AUTO_FIELD='django.db.models.BigAutoField',
TIME_ZONE='UTC',
USE_TZ=True,
)
apps.populate(settings.INSTALLED_APPS)
from django.db import models
from django_mysql.models import JSONField
# Define a simple Django model using Django-MySQL's JSONField
class MyModel(models.Model):
name = models.CharField(max_length=100)
data = JSONField(default=dict)
def __str__(self):
return self.name
# This code snippet would typically be followed by:
# python manage.py makemigrations myapp
# python manage.py migrate
# And then interactive usage:
# from myapp.models import MyModel
# instance = MyModel.objects.create(name='Sample Item', data={'version': 1, 'items': ['a', 'b']})
# print(f"Created: {instance.name} with data {instance.data}")
# instance.data['status'] = 'processed'
# instance.save()
# print(f"Updated: {instance.name} with data {instance.data}")
print("Django-MySQL model definition with JSONField is ready.")
Debug
Known issues
breakingDjango-MySQL has strict compatibility requirements with specific Django and Python versions. Upgrading Django or Python without checking `django-mysql`'s release notes can lead to compatibility errors.fixAlways consult the official `django-mysql` documentation and changelog for Python and Django compatibility before upgrading either library. For version 4.19.0, Python >= 3.9 and Django >= 3.2 are required.
affects: All major versions (e.g., 3.x to 4.x), particularly during Django or Python major version updates.
gotchaForgetting to add `'django_mysql'` to your `INSTALLED_APPS` in `settings.py` will prevent many features from working correctly, including the automatic registration of system checks.fixEnsure that `'django_mysql'` is present in your `INSTALLED_APPS` list in your Django project's `settings.py` file.
affects: All versions
breakingPrior to django-mysql 3.0, `JSONField` stored JSON as `TEXT`. From 3.0 onwards (Django 3.1+), it uses the native `JSON` column type for MySQL 5.7.8+ or MariaDB 10.2.3+.fixIf upgrading from an older version where `JSONField` was used and you were not using a native JSON column, you may need a data migration to convert your existing `TEXT` data to the native `JSON` type. Refer to the `django-mysql` 3.0 release notes for migration strategies.
affects: <3.0 to >=3.0
gotchaFields like `ListField` and `SetField` store Python lists/sets as serialized strings (VARCHAR/TEXT) in the database. While convenient, querying based on values *within* these lists/sets will not use database indexes efficiently and can lead to performance issues on large datasets.fixFor efficient querying of individual elements, consider normalizing your data into a separate many-to-many relationship or using `django_mysql.models.JSONField` with native JSON functions (if your MySQL version supports them) for structured data.
affects: All versions
Upgrade
Version history
4.19.0latest on PyPI · released Sep 18, 2025
Audit
Dependencies
DjangorequiredThis is a Django extension library and requires a compatible Django version to function.
mysqlclientoptionalDjango-MySQL requires a compatible MySQL database driver for Django, such as mysqlclient or PyMySQL.