Getting Started with mysqlclient: Troubleshooting Installation Problems on Ubuntu and MacOS

Sometimes, installing MySQLclient on Ubuntu or macOS can be tricky, whether you’re doing it for the first time or facing problems while setting up a new system or server. I’ve been there myself, and in this blog post, I’ll walk you through the process step by step. By the end of this blog, you’ll understand two things clearly:

1. Why installation errors happen.
2. How to fix these errors and successfully install MySQLclient.

Image with Mac on left and ubunto on right side screen and effortlessly working to resolve issue of mysqlclient

Let’s make mysqlclient installation easy on your Ubuntu or macOS system!

When you try to install ‘mysqlclient’ using ‘pip install mysqlclient’ for the first time, you might see an error message like this:

pkg-config issue on first try of installing mysql client.

The error message ‘pkg-config: not found’ appears when you try to install the ‘mysqlclient’ Python package. This package needs ‘pkg-config’ to find and set up things it depends on, like the MySQL client library. Without ‘pkg-config’, it can’t figure out how to put everything together, and the ‘mysqlclient’ installation fails.

Here are few reason why this could happen:

• You might not have ‘pkg-config’ installed on your computer. It’s a tool that helps manage dependencies for many programs on Ubuntu.
• You may be missing the development files for the MySQL client library (like ‘libmysqlclient-dev’) on your system. These files are necessary for building and connecting programs that use the MySQL client library. Usually, ‘pkg-config’ files come with these development packages.
• ‘pkg-config’ might not be set up correctly in your computer’s system settings, so it can’t be found when needed.

Lets give a try to install libmysqlclient-dev by use command below:

sudo apt-get install libmysqlclient-dev

If you have installed ‘libmysqlclient-dev’ but still ‘pkg-config: not found’ error raised, it might be because your computer has trouble finding the right path. Now first check the version of pkg-config using:

pkg-config --version

If it is not found then install it using:

sudo apt-get install pkg-config

Make sure the folder with ‘pkg-config’ is included in your computer’s PATH. You can check this by running the following command:

echo $PATH

Make sure /usr/bin (which typically contains pkg-config) is in your PATH. If it’s missing, add it to your PATH in your shell config file (like ~/.bashrc) by adding this line:

export PATH=$PATH:/usr/bin

Then, reload your shell configuration:

source ~/.bashrc

If you have done the earlier steps right, you might see a new error when you again try ‘pip install mysqlclient;’ it’ll say something about not being able to build ‘mysqlclient’ wheels.”

Error about faild building wheel for mysql client

Understanding Python Wheels: Why Build Them?
Think of a “wheel” like a ready-made cake that you can buy from the store. It’s already made and ready to eat, you don’t need to bake it from scratch.

In the same way, a “wheel” in Python is like a pre-made package that’s ready to use in your Python projects, you can just use it as-is. It makes installing packages easier and faster.
If mysqlclient has trouble building a wheel, it’s because of system-specific factors or requirements. Usually, mysqlclient comes with ready-made wheels for different OS and system setup but sometimes those don’t fit perfectly, so you have to make one just for your specific environment.

It’s like adjusting the seat in a car so you can reach the pedals comfortably.

To resolve this issue, you need to install the necessary build tools and dependencies. Here’s how you can do it:

sudo apt-get install build-essential python3-dev libmysqlclient-dev

build-essential: It provides necessary tools for building software.

python3-dev: These are development files for Python, useful for building Python programs.

libmysqlclient-dev: These are development files for the MySQL database, needed for certain software.

If pip install mysqlclient still doesn’t work, it might be because you haven’t followed the previous steps correctly. Additionally, you can try installing these packages:

sudo apt install libssl1.1 libssl1.1=1.1.1f-1ubuntu2 libssl-dev

For macOS:

Most of the explanations above for the need to install different tools and the issues apply to macOS as well. To resolve the issue on macOS, try using this command first:

brew install mysql-connector-c # macOS (Homebrew) (Currently, it has bug. See below)

Note about bug of MySQL Connector/C on macOS

See also: https://bugs.mysql.com/bug.php?id=86971

If the previous command doesn’t work, you can follow the instructions provided in the official ‘mysqlclient’ repository here: https://github.com/PyMySQL/mysqlclient?tab=readme-ov-file#macos-homebrew and your installation should be successful.