Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Django cannot load MySQLdb and asks whether mysqlclient is installed

Errordjango.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module: No module named MySQLdb

Short 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.

  • Applies to Django 5.2, mysqlclient 2.2, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1No module named MySQLdb, and pip show finds nothingmysqlclient is not installed in this environmentFix
    2. 2mysqlclient X or newer is required; you have YThe installed mysqlclient is older than Django allowsFix
    3. 3pip prints a compiler or pkg-config error instead of installingpip tries to build mysqlclient and the build failsFix

What does the error look like?

  • django.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module: No module named MySQLdb
  • Error 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 mysqlclient

3Verify

The import works and Django starts.

python -c "import MySQLdb"
python manage.py check

Confirmed by docs.djangoproject.com

Did this fix it?

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 mysqlclient

2Fix

Upgrade mysqlclient. If a requirements file pins an old version, change the pin as well.

python -m pip install --upgrade mysqlclient

3Verify

Run Django's own check.

python manage.py check

Confirmed by docs.djangoproject.com

Did this fix it?

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 mysqlclient

2Fix

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 mysqlclient

3Verify

Import the module.

python -c "import MySQLdb"

Confirmed by github.com

Did this fix it?

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:

Related fixes

Databases

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.