How to use PyMySQL with Django2020-02-04
mysqlclient is a Python 3 compatible fork of the original Python MySQL driver,
It still provides a Python module called
On install, it compiles against either the MariaDB client library or MySQL client library - whichever one you have installed.
Compiling against the C extension can be frustrating:
- It requires not only the MariaDB/MySQL client library, but also OpenSSL.
- Obtaining the C extension libraries might not be trivial on some platforms, such as AWS Lambda.
- After install, Pip’s wheel cache will store the one compiled version, so if you swap to another C library (e.g. MySQL -> MariaDB), the wheel might not work any more.
If these are blockers for you, an alternative is to use the PyMySQL library.
It’s a pure Python DB API driver - no C compilation necessary!
It’s also made by the same developers as
mysqlclient and is better maintained at this point.
Django doesn’t officially support it, but PyMySQL ships with an (undocumented) compatibility install that can help you use it. It’s an “at your own risk” feature. I’ve done this on one project and didn’t have any problems, but that’s no guarantee there aren’t some hidden bugs.
(I’d love to add PyMySQL support, I just haven’t had the time. If you’re interested in sponsoring such work, contact me.)
To use PyMySQL with Django, you need to run the compatibility install before Django tries to import
For Django 2.2+ you also need to patch PyMySQL to lie about its version.
This is to pass Django’s compatibility check, as per this comment from the PyMySQL lead developer.
You need to add this compatibility install before Django, or any other code, attempts to
You could do this in your
manage.py - this will work if it’s your only entrypoint, but in my experience projects often grow to add others, such as
The most universal place is in your settings file, around the definition of
Django hasn’t tried to import MySQLdb at this point, since it doesn’t know which database you want to use.
You can do this like so:
You can then verify that
import MySQLdb now produces the
pymysql module instead:
Enjoy using MariaDB / MySQL,
Interested in Django or Python training? I'm taking bookings for workshops.
One summary email a week, no spam, I promise.
© 2020 All rights reserved.