Friday, November 16, 2012

Is MySQLdb hard to install?

The short answer is: No. The longer answer is: It depends. With the latest version, most of the time, you can run:

pip install MySQL-python

and you're done... if you have the prerequisites. That's where it gets sticky.

The dreaded prerequisites

Since MySQLdb uses a C module to link against MySQL's client library, you will need:
  • A C compiler and associated toolchain
  • Python development headers and libraries
  • MySQL development headers and libraries


MySQLdb was originally developed specifically for use on Linux, as it was the only platform I cared about at the time. Over time, several Linux distributions (Red Hat, Debian, Ubuntu, etc.) picked it up, created their own packages, and distributed them. If you are a Linux user, I recommend you use your distributions packages. But what if you can't, and you really do need to build your own? Install using pip. Each Linux distribution has packages for all the prerequisites, but the names of these packages vary. For Ubuntu (and probably Debian):

apt-get install build-essential python-dev libmysqlclient-dev

Other UNIX-ish

MySQLdb has been a FreeBSD port for 12 years. Use it. Hey, if you're using FreeBSD or another *BSD, or Solaris, you probably don't need my help to install it...

Almost UNIX: Mac OS X

Mac OS X is very POSIX-like inside, and it so MySQLdb's setup treats it as POSIX, but it can get complicated. The simple part is: You need Xcode, which is Apple's compiler toolchain.

The easy way

By far the easiest way to get MySQLdb on the Mac is to use one of the two major UNIX-ish package distributions: MacPorts or Homebrew. Of the two, I have only used MacPorts. Once upon a time, everything in MacPorts had to be built from sources, like a *BSD or Gentoo-style port system, but there are now binary packages for many things. Some people swear by Homebrew. Either one will make your life easier. MacPorts has a port for MySQLdb (py-mysql and variants). If Homebrew has a "formula", I can't find it, but a pip install should work once you have compatible versions of Python and MySQL.

The hard way

The hard part about the Mac is, there are three architectures you could be building for: PowerPC, Intel 32-bit, and Intel 64-bit. We can safely ignore Motorola since Apple hasn't used them in a very long time, and PowerPC can be mostly ignored, but you still see some support for it. For example, the Python Apple distributes in Snow Leopard is a fat binary that includes code for PPC, i386, and x86_64. You might think this makes things easier, but it does not. If you're on any sort of modern Mac, it's going to use the x86_64 support. That means the version of MySQL you use also has to be built for x86_64. You can't mix and match.

Most people who are going to use Xcode instead of MacPorts or Homebrew are probably going to download binary packages of MySQL from They have separate 32-bit and 64-bit packaging, i.e. no fat binaries. You almost certainly want 64-bit packages. Another option is to download their Connector/C package, and here you will find 32-bit and 64-bit Intel and PowerPC as well. You could also download the source and build it yourself.

Once you have MySQL on your Mac, make sure you can run mysql_config from a shell. If it's not on your executable PATH, you'll have to hack on site.cfg to tell where it is.

One issue I have seen recently was ultimately an architecture mismatch problem, and even once that was fixed, the loader path had to be fixed in the environment, which is not ideal.

Windows sucks

Even though Windows sucks, current versions of MySQLdb build on Windows without a lot of drama.

For the build toolchain, you must have Visual Studio 2008, and specifically you need vcsetup.exe for the C compiler. It has to be the 2008 version because that's the version the Python packaging uses. (Of course, if you're building your own Python, you're on your own here.) Like with the Mac folks, you have 32-bit and 64-bit options. Choose the same one for Connector/C. If you are building a 32-bit package, it should work, period. 64-bit I'm not so sure about. But I've been building 32-bit MSI packages, and pip install should grab one of those if you're using a 32-bit Python, and that is really all you need.


Is it simple? Yes, for most people. Most of the hard work has done for you. So if it's so simple, why don't I have more binary packages? Mainly because, there are several different versions of both Python and MySQL that you might choose to use at any given time, depending on your needs, and you might still choose 32-bit or 64-bit architectures. It's just not practical for me to build all of them. Maybe with some kind of a build-bot. This could change in the future, but for now, there are plenty of other open source package distributors out there, and if at all possible, you should just use a pre-built package.


irmen said...

For windows, don't bother with compiling stuff. Grab a binary installer instead:

Unknown said...

Or like I said, use pip install, since I have a Windows MSI binary on PyPI.

Anonymous said...

Installing via "pip install mysql-python" doesn't work on Windows, it will still try to download the source and compile it. Not that it is THAT hard to just download it yourself and do "easy_install " - just wanted to mention it.

Anonymous said...

When will a Python 3 version will be ready?

Unknown said...

I have a github branch for 1.3, which targets only Python 2.7 and 3.x. At the moment, there is a serious crash bug somewhere in the C module, but only for Python 3. Lately I've been using a Windows laptop to develop on, and I don't really have a good tool for analyzing what is causing the crash. I need to try it on a Linux box where I have gdb, and then maybe I can figure it out.

The Python-3 compatibility is otherwise not very far off. The Python portion should be ready or nearly ready. It's using six to be compatible with Python 2.7 and 3.x in the same codebase.