Although Python's extensive standard library covers many programming

needs, there often comes a time when you need to add some new

functionality to your Python installation in the form of third-party

modules. This might be necessary to support your own programming, or to

support an application that you want to use and that happens to be

written in Python.

In the past, there has been little support for adding third-party

modules to an existing Python installation. With the introduction of

the Python Distribution Utilities (Distutils for short) in Python 1.6,

this is starting to change. Not everything will change overnight,

though, so while this document concentrates on installing module

distributions that use the Distutils, we will also spend some time

dealing with the old ways.

This document is aimed primarily at the people who need to install

third-party Python modules: end-users and system administrators who just

need to get some Python application running, and existing Python

programmers who want to add some new goodies to their toolbox. You

don't need to know Python to read this document; there will be some

brief forays into using Python's interactive mode to explore your

installation, but that's it. If you're looking for information on how

to distribute your own Python modules so that others may use them, see

the ``Distributing Python Modules'' manual.

\subsection{Best case: trivial installation}

\label{sec:trivial-inst}

In the best case, someone will have prepared a special version of the

module distribution you want to install that is targeted specifically at

your platform and is installed just like any other software on your

platform. For example, the module developer might make an executable

installer available for Windows users, an RPM package for users of

RPM-based Linux systems (Red Hat, SuSE, Mandrake, and many others), a

Debian package for users of Debian-based Linux systems (Debian proper,

Caldera, Corel, etc.), and so forth.

In that case, you would download the installer appropriate to your

platform and do the usual thing with it: run it if it's an executable

installer, \code{rpm -I} it if it's an RPM, etc. You don't need to run

Python or a setup script, you don't need to compile anything---you might

not even need to read any instructions (although it's always a good idea

to do so anyways).

Of course, things will not always be that easy. You might be interested

in a module distribution that nobody has created an easy-to-use

installer for use on your platform. In that case, you'll have to start

with the source distribution released by the module's

author/maintainer. Installing from a source distribution is not too

hard, as long as the modules are packaged in the standard way. The bulk

of this document is about building and installing modules that were

packaged in the standard way.

\subsection{The new standard: Distutils}

\label{sec:new-standard}

If you download a module source distribution, you can tell pretty

quickly if was packaged and distributed in the standard way, i.e. using

the Distutils. First, the distribution's name and version number will

be featured prominently in the name of the downloaded archive, e.g.

\file{foo-1.0.tar.gz} or \file{widget-0.9.7.zip}. Next, the archive

will unpack into a similarly-named directory: \file{foo-1.0} or

\file{widget-0.9.7}. Additionally, the distribution will contain a

setup script \file{setup.py}, and a \file{README.txt} (or possibly

\file{README}), which should explain that building and installing the

module distribution is a simple matter of running

\begin{verbatim}

\end{verbatim}

If all these things are true, then you already know how to build and

install the modules you've just downloaded: run the command above.

Unless you need to install things in a non-standard way or customize the

build process, you don't really need this manual. Or rather, the above

command is everything you need to get out of this manual.

\subsection{The old way: no standards}

\label{sec:old-way}

Before the Distutils, there was no infrastructure to support installing

third-party modules in a consistent, standardized way. Thus, it's not

really possible to write a general manual for installing Python modules

that don't use the Distutils; the only truly general statement that can

be made is, ``Read the module's own documentation on installation.''

However, such documentation is often woefully inadequate, assuming that

you are familiar with how the Python library is laid out and will

somehow just know where to copy various files in order for Python to

find them. Also, since there is only one way to lay out the Python

library on a given platform, this manual is a good place to learn that

layout. That way, if you do have to manually install an old,

pre-Distutils module distribution, you won't be completely on your own.

Additionally, while there has not previously been a standard

installation mechanism, Python has had some standard machinery for

building extensions on Unix since Python \XXX{version?}. This machinery

(the \file{Makefile.pre.in} file) is superseded by the Distutils, but it

will no doubt live on in older module distributions for a while. This

\file{Makefile.pre.in} mechanism is documented in the ``Extending \&

Embedding Python'' manual, but that manual is aimed at module

developers---hence, we include documentation for builders/installers

here.

All of the pre-Distutils material is tucked away in

section~\ref{sec:pre-distutils}.

As described in section~\ref{sec:new-standard}, building and installing

a module distribution using the Distutils is usually one simple command:

\begin{verbatim}

\end{verbatim}

On Unix, you'd run this command from a shell prompt; on Windows, you

have to open a command prompt window and do it there; on Mac OS ...

\XXX{what the heck do you do on Mac OS?}.

\subsection{Platform variations}

You should always run the setup command from the distribution root

directory, i.e. the top-level subdirectory that the module source

distribution unpacks into. For example, if you've just downloaded a

module source distribution \file{foo-1.0.tar.gz} onto a Unix system, the

normal thing to do is:

\begin{verbatim}

\end{verbatim}

On Windows, you'd probably unpack the archive before opening the command

prompt. If you downloaded the archive file to \file{C:\bslash{}Temp}, then

it probably unpacked (depending on your software) into

\file{C:\bslash{}Temp\bslash{}foo-1.0}; from the command prompt window, you would

then run

\begin{verbatim}

\end{verbatim}

On Mac OS, ... \XXX{again, how do you run Python scripts on Mac OS?}

\subsection{Splitting the job up}

Running \code{setup.py install} builds and installs all modules in one

fell swoop. If you prefer to work incrementally---especially useful if

you want to customize the build process, or if things are going

wrong---you can use the setup script to do one thing at a time.

For example, you can build everything in one step, and then install

everything in a second step, by invoking the setup script twice:

\begin{verbatim}

\end{verbatim}

(If you do this, you will notice that running the \command{install}

command first runs the \command{build} command, which will quickly

notice that it has nothing to do, since everything in the \file{build}

directory is up-to-date.

\XXX{how do MacPython users run the interpreter with command-line args?}

\XXX{Corran Webster says: ``Modules are found in either \file{:Lib} or

non-pure distributions''. Is this necessary?!?}

\filevar{prefix} (\XXX{should have a section describing .pth files and

cross-ref it here}).

\XXX{need some Windows and Mac OS examples---when would custom

installation schemes be needed on those platforms?}

\section{Distutils Configuration Files}

\section{Pre-Distutils Conventions}

\label{sec:pre-distutils}

\subsection{The \protect\file{Makefile.pre.in} file}

\label{sec:makefile-pre-in}

\subsection{Installing modules manually}

\label{sec:manual-install}