How you get MySQL for Python depends on your
operating system and the level of authorization you have on it. In the
following subsections, we walk through the common operating systems and
see how to get MySQL for Python on each.
Using a package manager (only on Linux)
Package managers are used
regularly on Linux, but none come by default with Macintosh and Windows
installations. So users of those systems can skip this section.
A package manager takes care
of downloading, unpacking, installing, and configuring new software for
you. In order to use one to install software on your Linux installation,
you will need administrative privileges.
Administrative privileges on a Linux system can be obtained legitimately in one of the following three ways:
Log into the system as the root user (not recommended)
Switch user to the root user using su
Use sudo to execute a single command as the root user
The first two require
knowledge of the root user's password. Logging into a system directly as
the root user is not recommended due to the fact that there is no
indication in the system logs as to who used the root account. Logging
in as a normal user and then switching to root using su
is better because it keeps an account of who did what on the machine
and when. Either way, if you access the root account, you must be very
careful because small mistakes can have major consequences. Unlike other
operating systems, Linux assumes that you know what you are doing if
you access the root account and will not stop you from going so far as
deleting every file on the hard drive.
Unless you are familiar with Linux system administration, it is far better, safer, and more secure to prefix the sudo command to the package manager
call. This will give you the benefit of restricting use of
administrator-level authority to a single command. The chances of
catastrophic mistakes are therefore mitigated to a great degree.
More information on any of these commands is available by prefacing either man or info before any of the preceding commands (su, sudo).
Which package manager you use
depends on which of the two mainstream package management systems your
distribution uses. Users of RedHat or Fedora, SUSE, or Mandriva will use
the RPM Package Manager (RPM) system. Users of Debian, Ubuntu, and other Debian-derivatives will use the apt suite of tools available for Debian installations. Each package is discussed in the following:
Using RPMs and yum
If you use SUSE, RedHat, or Fedora, the operating system comes with the yum package manager. You can see if MySQLdb is known to the system by running a search (here using sudo):
If yum returns a hit, you can then install MySQL for Python with the following command:
Using RPMs and urpm
If you use Mandriva, you will need to use the urpm package manager in a similar fashion. To search use urpmq:
And to install use urpmi:
Using apt tools on Debian-like systems
Whether you run a version of Ubuntu, Xandros, or Debian, you will have access to aptitude, the default Debian package manager. Using sudo we can search for MySQLdb in the apt sources using the following command:
sudo aptitude search mysqldb
On most Debian-based distributions, MySQL for Python is listed as python-mysqldb.
Once you have found how apt references MySQL for Python, you can install it using the following code:
sudo aptitude install python-mysqldb
Using a package manager automates the entire process so you can move to the section Importing MySQL for Python.
Using an installer for Windows
Windows users will need to use the older 1.2.2 version of MySQL for Python. Using a web browser, go to the following link:
http://sourceforge.net/projects/mysql-python/files/
This page offers a listing of all available files for all platforms. At the end of the file listing, find mysql-python and click on it. The listing will unfold to show folders containing versions of MySQL for Python back to 0.9.1. The version we want is 1.2.2.
Windows binaries do
not currently exist for the 1.2.3 version of MySQL for Python. To get
them, you would need to install a C compiler on your Windows
installation and compile the binary from source.
Click on 1.2.2
and unfold the file listing. As you will see, the Windows binaries are
differentiated by Python version—both 2.4 and 2.5 are
supported. Choose the one that matches your Python installation and
download it. Note that all available binaries are for 32-bit Windows
installations, not 64-bit.
After downloading the
binary, installation is a simple matter of double-clicking the
installation EXE file and following the dialogue. Once the installation
is complete, the module is ready for use. So go to the section Importing MySQL for Python.
Using an egg file
One of the easiest ways to obtain MySQL for Python is as an egg file, and it is best to use one of those files if you can. Several advantages can be gained from working with egg files such as:
They can include metadata about the package, including its dependencies
They allow for the use of egg-aware software, a helpful level of abstraction
Eggs can, technically, be placed on the Python executable path and used without unpacking
They save the user from installing packages for which they do not have the appropriate version of software
They are so portable that they can be used to extend the functionality of third-party applications
Installing egg handling software
One of the best known egg utilities—Easy Install, is available from the PEAK Developers' Center at http://peak.telecommunity.com/DevCenter/EasyInstall.
How you install it depends on your operating system and whether you
have package management software available. In the following section, we
look at several ways to install Easy Install on the most common systems.
Using a package manager (Linux)
On Ubuntu you can try the following to install the easy_install tool (if not available already):
shell> sudo aptitude install python-setuptools
On RedHat or CentOS you can try using the yum package manager:
shell> sudo yum install python-setuptools
On Mandriva use urpmi:
shell> sudo urpmi python-setuptools
You must have administrator privileges to do the installations just mentioned.
Without a package manager (Mac, Linux)
If you do not have access
to a Linux package manager, but nonetheless have a Unix variant as your
operating system (for example, Mac OS X), you can install Python's
setuptools manually. Go to:
http://pypi.python.org/pypi/setuptools#files
Download the relevant egg file for your Python version.
When the file is downloaded, open a terminal and change to the download directory. From there you can run the egg file as a shell script. For Python 2.5, the command would look like this:
sh setuptools-0.6c11-py2.5.egg
This will install several files, but the most important one for our purposes is easy_install, usually located in /usr/bin.
On Microsoft Windows
On Windows, one can download the setuptools suite from the following URL:
http://pypi.python.org/pypi/setuptools#files
From the list located there, select the most appropriate Windows executable file.
Once the download is
completed, double-click the installation file and proceed through the
dialogue. The installation process will set up several programs, but the
one important for our purposes is easy_install.exe. Where this is located will differ by installation and may require using the search function from the Start Menu.
On 64-bit Windows, for example, it may be in the Program Files (x86) directory. If in doubt, do a search. On Windows XP with Python 2.5, it is located here:
C:\Python25\Scripts\easy_install.exe
Note that you may
need administrator privileges to perform this installation. Otherwise,
you will need to install the software for your own use. Depending on the
setup of your system, this may not always work.
Installing software on Windows for your own use requires the following steps:
1 Copy the setuptools installation file to your Desktop.
2 Right-click on it and choose the runas option.
3 Enter the name of the user who has enough rights to install it (presumably yourself).
After the software has been installed, ensure that you know the location of the easy_install.exe file. You will need it to install MySQL for Python.
Installing MySQL for Python from an egg file
After installing EasyInstall, you still need to install the MySQL for Python egg. The egg files for MySQL for Python can be downloaded from the following URL:
http://sourceforge.net/projects/mysql-python/files/
There you will see a list of all available files relevant to MySQL for Python.
Which one you use depends on your operating system and your installed Python version. Currently, the only egg files available for MySQL for Python version 1.2.3c1 are for Linux running either Python 2.5 or 2.6. Mac users should use a tarball (tar.gz) file as discussed in the next section.
To get an egg file for Windows, click on the MySQL-python directory and select the 1.2.2
version. This is the same directory used for the Windows binaries . This time, however, you need to
select an egg for Windows that fits either Python 2.4 or 2.5. There is no 2.6 version.
Once you have the egg file for MySQL for Python, you simply need to invoke EasyInstall over the newly-downloaded egg file. How you do that will depend on the permissions you have for your operating system.
With administrator permissions, you can simply call the EasyInstall binary. For Linux, it will look like this:
shell> easy_install <name of egg file>
For Windows, you will use a command similar to this one:
C:\Python25\Scripts\easy_install.exe <name of egg file>
Note that you must have
administrator privileges to do this. Otherwise, Windows users will have
to install the software locally. Linux users can use sudo.
EasyInstall will then unpack the archive, install it in your default Python installation folders, and configure it for immediate use.
For Windows users, if you had to install setuptools locally, you may also require a local installation of Python itself in order to install MySQL for Python. See the section On Microsoft Windows under Installing egg-handling software,
for help with this. If you need to go through this process, all of your
configurations will be local, so you are best to use full path
command-line calls.
If your system has MySQL, Python, and setuptools, but you still don't have administrative access, it is advisable to unpack the egg file manually and call it as a local module. To do this, use an archiving program to unzip the file.
The content listing for the Windows egg will look like this:
Egg-info
MySQLdb
_mysql_exceptions.py
_mysql_exceptions.pyc
_mysql.py
_mysql.pyc
_mysql.pyd
And the Linux egg unpacks to the following files:
Egg-info
MySQLdb
_mysql_exceptions.py
_mysql_exceptions.pyc
_mysql.py
_mysql.pyc
_mysql.so
With the exception of the egg-info
directory, the contents are the basic ingredients of a Python module
and can be imported locally if one's program resides in the same
directory as the files are located.
Using a tarball (tar.gz file)
Due to the need for certain
programming libraries, this method of installation applies only to users
of Unix-derived operating systems. This method involves installing from
the source files and so requires the necessary C libraries to compile a
binary version. Windows users should therefore use one of the other
methods discussed previously.
If you cannot use egg files or if you use an earlier version of Python, you should use the tar.gz file, a tar and gzip archive. The tar.gz archive follows the Linux egg files in the file listing. The current version of MySQL for Python is 1.2.3c1, so the file we want is as following:
MySQL-python-1.2.3c1.tar.gz
This method is by far more
complicated than the others. If at all possible, use your operating
system's installation method or an egg file.
This version of MySQL for
Python is compatible up to Python 2.6. It is worth noting that MySQL for
Python has not yet been released for Python 3.0 or later versions. In
your deployment of the library, therefore, ensure that you are running
Python 2.6 or earlier. As noted, Python 2.5 and 2.6 have
version-specific releases. Prior to Python 2.4, you will need to use
either a tar.gz version of the latest release or use an older version of MySQL for Python. The latter option is not recommended.
Most Unix-derived operating systems (Linux, Mac) come with the tar and gzip utilities pre-installed. For users of these systems, unpacking the archive is as simple as the following command:
shell> tar xvzf MySQL-python-1.2.3c1.tar.gz
The archive will then unpack into a directory called MySQL-python-1.2.3c1.
Windows users can use any of the following archive programs to unpack the tarball:
PowerArchiver 6.1
7-Zip
WinZip
Once the file is unpacked, you need to ensure that you have the program mysql_config in your path. For Mac users, this usually comes with the MySQL installation itself. For Linux, if you are using bash or another shell with command-line completion, you can check this by typing the following in a terminal:
Then press the tab key. If the command is completed to mysql_config,
there are no issues, otherwise your operating system does not know of
any such command, and you need to either find it or install it.
An alternative way of checking is to use the whereis command. Type the following from the command-line:
shell> whereis mysql_config
If it is installed, the system will return its location. Then echo your current PATH value by typing:
and compare the results. If the location of mysql_config is one of the values in your path, there are no issues otherwise, we need to either find it or install it.
The mysql_config
program comes with the MySQL client development libraries. If you have
these installed, check the directory that holds the MySQL client binary
(use whereis mysql if necessary). If you are unsure, you can check with a package manager using the following commands:
shell> aptitude search mysql | grep client | grep dev
This will work for Debian-based systems. Users of RPM-based systems should substitute either yum search or urpmq for aptitude search.
This query will return results for the development files and for the
MySQL client, and you can then see if the appropriate package is
installed. If it is not, you can install it with the install argument (for either aptitude or yum) or by using urpmi.
If the mysql_config program is
installed, but is outside your path, you need to indicate its location
to the MySQL for Python setup configuration. Navigate to the MySQL-python-1.2.3c1 directory and open the file site.cfg in your favorite text editor. The file is not large, and the following section is easily seen as the second part of the file:
#The path to mysql_config
#Only use this if mysql_config is not on your PATH, or you have some weird setup that requires it
#mysql_config = /usr/local/bin/mysql_config
If mysql_config is outside of your path, uncomment the last line of the part cited here and enter the correct path. So, if mysql_config is installed to:
/usr/local/bin/mysql/bin/mysql_config
The last line should read:
mysql_config = /usr/local/bin/mysql/bin/mysql_config
Then save the file and close it.
Next, we should build the package using the instructions that came with it in setup.py. Use the following command to attempt a build without installing it:
shell> python setup.py build
If the process goes
through without error, which it usually does, the build is successful.
If there is an error, it usually involves the lack of a module or
software package. In which case, confirm that you have all the
prerequisites needed for the task by checking the list in the readme file that comes with the archive.
Be sure to read the readme file that comes with the source code. It contains a lot of help on the installation process.
Once the build is successful, installation can be done with the following command:
shell> python setup.py install
Note that you will need super user access for this. If you do not have administrative access to your system, you need to use one of the other methods.