Django cannot load MySQLdb and asks whether mysqlclient is installed
django.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module: No module named MySQLdbShort answer
Django's MySQL backend imports MySQLdb, which is provided by the mysqlclient package. Install it with pip install mysqlclient into the same environment that runs manage.py, not MySQLdb or MySQL-python. If it is installed but too old, upgrade it: current Django needs mysqlclient 1.4.3 or later. A failed build points to missing MySQL headers.
Fix it fast
1Find out which cause you have
Ask the exact Python that runs Django whether it can import the module and which mysqlclient it has.
python -c "import sys; print(sys.executable)" python -m pip show mysqlclient python -c "import MySQLdb"2Match what you see, then jump to its fix
- 1
No module named MySQLdb, and pip show finds nothingmysqlclient is not installed in this environmentFix - 2
mysqlclient X or newer is required; you have YThe installed mysqlclient is older than Django allowsFix - 3
pip prints a compiler or pkg-config error instead of installingpip tries to build mysqlclient and the build failsFix
- 1
What does the error look like?
django.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module: No module named MySQLdbError loading MySQLdb module: Did you install mysqlclient or MySQL-python?mysqlclient 1.3.13 or newer is required; you have 0.9.3
Cause 1 of 3
mysqlclient is not installed in this environment
1Check
pip show prints nothing for mysqlclient, or the interpreter path is not your project's virtual environment.
python -m pip show mysqlclient
python -c "import sys; print(sys.prefix)"2Fix
Install the package under its real name into the active environment. The Django documentation recommends mysqlclient as the MySQL driver, and mysqlclient's own install command is pip install mysqlclient.
python -m pip install mysqlclient3Verify
The import works and Django starts.
python -c "import MySQLdb"
python manage.py checkConfirmed by docs.djangoproject.com
Cause 2 of 3
The installed mysqlclient is older than Django allows
1Check
Compare the version pip show prints with the minimum in the Django databases page, which is mysqlclient 1.4.3 or later for current releases.
python -m pip show mysqlclient2Fix
Upgrade mysqlclient. If a requirements file pins an old version, change the pin as well.
python -m pip install --upgrade mysqlclient3Verify
Run Django's own check.
python manage.py checkConfirmed by docs.djangoproject.com
Cause 3 of 3
pip tries to build mysqlclient and the build fails
1Check
The project's README says a prebuilt Windows wheel is used when one exists for your Python; otherwise mysqlclient is built from source and needs MySQL client development headers and pkg-config.
python --version
python -m pip install mysqlclient2Fix
Install the build prerequisites for your platform, then run pip again. The README gives these for Ubuntu and macOS.
# Debian / Ubuntu
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential pkg-config
# macOS (Homebrew)
brew install mysql pkg-config
# then
python -m pip install mysqlclient3Verify
Import the module.
python -c "import MySQLdb"Confirmed by github.com
How do I stop it coming back?
- List mysqlclient in requirements.txt or pyproject.toml so every environment and image installs it.
- Run pip with python -m pip so it always targets the interpreter you will run Django with.
- Rebuild the Docker image after changing database drivers, and install the system headers in the build stage.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Databases
pip install mysqlclient fails to build on Windows, Linux or macOS
error: metadata-generation-failed
mysqlclient is a C extension.
3 causes, each with a fixDatabases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
python manage.py migrate finishes but the tables for my app are missing
relation "myapp_book" does not exist
migrate only applies migration files that exist.
3 causes, each with a fixDatabases
MySQL error 3159: connections using insecure transport are prohibited
ER_SECURE_TRANSPORT_REQUIRED
Error 3159 means the server has require_secure_transport turned on and your client connected over plain TCP.
3 causes, each with a fixDatabases
pip install mysqlclient fails on a Mac
The build output mentions pkg-config or the MySQL client library
mysqlclient is a C extension, so pip compiles it against the MySQL client library and finds that library with pkg-config.
3 causes, each with a fixDatabases
pandas read_sql fails with Execution failed on sql ... sqlite_master on a MySQL connection
Execution failed on sql 'SELECT name FROM sqlite_master WHERE type='table' AND name=?;'
pandas supports a plain DBAPI connection only for sqlite3.
3 causes, each with a fix