{{{
#!text/x-rst
==================================
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.

.. __: https://www.sqlite.org/json1.html
.. __: https://docs.python.org/3/library/sqlite3.html#module-sqlite3

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.

.. __: https://www.sqlite.org/download.html
.. __: https://www.sqlite.org/howtocompile.html

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.

.. __: https://www.sqlite.org/download.html

}}}