Enabling JSON1 extension on SQLite

To use django.db.models.JSONField on SQLite, you need to enable the JSON1 extension on Python's sqlite3 library. If the extension is not enabled on your installation, a system error (fields.E180) will be raised. To check if the extension is enabled on your installation, you can do a query with one of the functions included in the extension, e.g. JSON(). For example:

>>> import sqlite3
>>> conn = sqlite3.connect(':memory:')
>>> cursor = conn.cursor()
>>> cursor.execute('SELECT JSON(\'{"a": "b"}\')')

If the query doesn't throw any errors, then the JSON1 extension is already enabled. Otherwise, follow the instructions below according to your operating system to set it up correctly.

Linux

On most major Linux distributions, the JSON1 extension is included in their SQLite and/or Python packages and enabled by default. If that's not the case on your installation, then do the following:

• Download the SQLite amalgamation, with or without the configuration script.

• Extract the source code archive and enter the directory of the result.

• Compile the source code using the -DSQLITE_ENABLE_JSON1 flag to enable the JSON1 extension. For example:

  gcc -DSQLITE_ENABLE_JSON1 -c -fPIC sqlite3.c
  

  To enable other extensions, see the compilation instructions.

• Create a shared library. For example:

  gcc -shared -o libsqlite3.so -fPIC sqlite3.o -ldl -lpthread
  

• Place the resulting file (libsqlite3.so) in a desired directory, e.g. /usr/lib/sqlite3/.

• Set the LD_PRELOAD environment variable to use your compiled SQLite every time you run Django. For example:

  export LD_PRELOAD=/usr/lib/sqlite3/libsqlite3.so
  

• Now, the JSON1 extension should be ready to be used in Python and Django.

macOS

On macOS, follow the instructions for Linux above, but instead of setting the LD_PRELOAD environment variable, use DYLD_LIBRARY_PATH. For example:

export DYLD_LIBRARY_PATH=/usr/lib/sqlite3

Windows

• Download the precompiled DLL that matches your Python installation (32-bit or 64-bit).
• Locate your Python installation. By default, it should be in %localappdata%\Programs\Python\PythonXX, where XX is the Python version. For example, it's located in C:\Users\<username>\AppData\Local\Programs\Python\Python37. If you added Python installation directory to your PATH environment variable, you can run the command where python on a command prompt to locate it.
• Enter the DLLs directory in your Python installation.
• Rename (or delete) sqlite3.dll inside the DLLs directory.
• Extract sqlite3.dll from the downloaded DLL archive and put it in the DLLs directory.
• Now, the JSON1 extension should be ready to be used in Python and Django.