When you are installing the mysqlclient Python library on your computer, you may encounter an error saying Failed building wheel for mysqlclient as shown below:
$ pip install mysqlclient
# ...
Failed building wheel for mysqlclient
Running setup.py clean for mysqlclient
Failed to build mysqlclient
In Python, a wheel is a package format that contains the instruction for the Python version and platforms supported by the package, as well as the package you wish to install that’s already built.
Sometimes, when the package is not in a wheel format, pip will try to build the package into a wheel to make the installation process go faster.
In the case of the above, the mysqlclient library is not in a wheel package, and the attempted wheel build for mysqlclient by pip fails.
Even though the wheel build fails, pip may still successfully install mysqlclient if you see the following message:
Failed building wheel for mysqlclient
Running setup.py clean for mysqlclient
Failed to build mysqlclient
Installing collected packages: mysqlclient
Running setup.py install for mysqlclient ... done
Successfully installed mysqlclient-2.1.0
As you can see, when the wheel build fails, pip use the setup.py install command and attempt to install mysqlclient directly.
If successful, then you can safely ignore the Failed building wheel error and use the library in your project.
But most often, you may see the setup.py install command returns an error:
Failed building wheel for mysqlclient
Running setup.py clean for mysqlclient
Failed to build mysqlclient
Installing collected packages: mysqlclient
Running setup.py install for mysqlclient ... error
When this happens, then you need to fix the error so that mysqlclient can be installed on your computer.
The best way to fix this error is to follow the instruction written on mysqlclient GitHub page
Based on the operating system you have on your computer, there are different ways to resolve the error.
Fix Failed building wheel MySQL for Windows
For Windows, you may need to install Microsoft Visual Studio and its build tools.
Here’s a direct link to the build tools of MS Visual Studio 2022
Once installed, you can try running pip install mysqlclient again.
Fix Failed building wheel MySQL for Linux
For Linux OS, you need to install the required dependencies from apt-get (Debian/ Ubuntu) or yum (Red Hat/ CentOS)
Use one of the following commands to install the dependencies:
# For Debian/ Ubuntu
sudo apt-get install python3-dev default-libmysqlclient-dev build-essential
# For Red Hat/ CentOS
sudo yum install python3-devel mysql-devel
Once the installation above is finished, try to run pip install mysqlclient again on your computer.
Fix failed building wheel for macOS
For macOS, you need to install MySQL and Python 3 using Homebrew with the following command:
brew install mysql python
Don’t use the default Python 2 that’s pre-installed on your Mac because mysqlclient latest version only supports Python 3 (requires Python >=3.5)
Also, don’t install Python 3 using pyenv because it may have compatibility issues.
When installing Python 3 with Homebrew, you can issue the python3 and pip3 commands from the command line:
python --version
# Python 2.7.16
python3 --version
# Python 3.9.9
pip3 --version
# pip 21.3.1 from /opt/homebrew/lib/python3.9/site-packages/pip (python 3.9)
Once you have both python3 and pip3 commands available, it’s time to install mysqlclient package.
You should see an output similar to the one below:
pip3 install mysqlclient
Building wheels for collected packages: mysqlclient
Building wheel for mysqlclient (setup.py) ... done
# ...
Successfully built mysqlclient
Installing collected packages: mysqlclient
Successfully installed mysqlclient-2.1.0
And that’s how you can fix the Failed building wheel for mysqlclient error.
Keep in mind that as long as the package installation is successful, you can ignore the error and use the package in your Python project anyway.