ActivePython 2.5 - Online Docs : 3 Alternate Installation

Often, it is necessary or desirable to install modules to a location other than the standard location for third-party Python modules. For example, on a Unix system you might not have permission to write to the standard third-party module directory. Or you might wish to try out a module before making it a standard part of your local Python installation. This is especially true when upgrading a distribution already present: you want to make sure your existing base of scripts still works with the new version before actually upgrading.

The Distutils install command is designed to make installing module distributions to an alternate location simple and painless. The basic idea is that you supply a base directory for the installation, and the install command picks a set of directories (called an installation scheme) under this base directory in which to install files. The details differ across platforms, so read whichever of the following sections applies to you.

3.1 Alternate installation: the home scheme

The idea behind the ``home scheme'' is that you build and maintain a personal stash of Python modules. This scheme's name is derived from the idea of a ``home'' directory on Unix, since it's not unusual for a Unix user to make their home directory have a layout similar to /usr/ or /usr/local/. This scheme can be used by anyone, regardless of the operating system their installing for.

python setup.py install --home=<dir>

where you can supply any directory you like for the --home option. On Unix, lazy typists can just type a tilde (~); the install command will expand this to your home directory:

python setup.py install --home=~

The --home option defines the installation base directory. Files are installed to the following directories under the installation base as follows:

Type of file	Installation Directory	Override option
pure module distribution	home/lib/python	--install-purelib
non-pure module distribution	home/lib/python	--install-platlib
scripts	home/bin	--install-scripts
data	home/share	--install-data

Changed in version 2.4: The --home option used to be supported only on Unix.

3.2 Alternate installation: Unix (the prefix scheme)

The ``prefix scheme'' is useful when you wish to use one Python installation to perform the build/install (i.e., to run the setup script), but install modules into the third-party module directory of a different Python installation (or something that looks like a different Python installation). If this sounds a trifle unusual, it is--that's why the ``home scheme'' comes first. However, there are at least two known cases where the prefix scheme will be useful.

First, consider that many Linux distributions put Python in /usr, rather than the more traditional /usr/local. This is entirely appropriate, since in those cases Python is part of ``the system'' rather than a local add-on. However, if you are installing Python modules from source, you probably want them to go in /usr/local/lib/python2.X rather than /usr/lib/python2.X. This can be done with

/usr/bin/python setup.py install --prefix=/usr/local

Another possibility is a network filesystem where the name used to write to a remote directory is different from the name used to read it: for example, the Python interpreter accessed as /usr/local/bin/python might search for modules in /usr/local/lib/python2.X, but those modules would have to be installed to, say, /mnt/@server/export/lib/python2.X. This could be done with

/usr/local/bin/python setup.py install --prefix=/mnt/@server/export

In either case, the --prefix option defines the installation base, and the --exec-prefix option defines the platform-specific installation base, which is used for platform-specific files. (Currently, this just means non-pure module distributions, but could be expanded to C libraries, binary executables, etc.) If --exec-prefix is not supplied, it defaults to --prefix. Files are installed as follows:

Type of file	Installation Directory	Override option
pure module distribution	prefix/lib/python2.X/site-packages	--install-purelib
non-pure module distribution	exec-prefix/lib/python2.X/site-packages	--install-platlib
scripts	prefix/bin	--install-scripts
data	prefix/share	--install-data

There is no requirement that --prefix or --exec-prefix actually point to an alternate Python installation; if the directories listed above do not already exist, they are created at installation time.

Incidentally, the real reason the prefix scheme is important is simply that a standard Unix installation uses the prefix scheme, but with --prefix and --exec-prefix supplied by Python itself as sys.prefix and sys.exec_prefix. Thus, you might think you'll never use the prefix scheme, but every time you run python setup.py install without any other options, you're using it.

Note that installing extensions to an alternate Python installation has no effect on how those extensions are built: in particular, the Python header files (Python.h and friends) installed with the Python interpreter used to run the setup script will be used in compiling extensions. It is your responsibility to ensure that the interpreter used to run extensions installed in this way is compatible with the interpreter used to build them. The best way to do this is to ensure that the two interpreters are the same version of Python (possibly different builds, or possibly copies of the same build). (Of course, if your --prefix and --exec-prefix don't even point to an alternate Python installation, this is immaterial.)

3.3 Alternate installation: Windows (the prefix scheme)

Windows has no concept of a user's home directory, and since the standard Python installation under Windows is simpler than under Unix, the --prefix option has traditionally been used to install additional packages in separate locations on Windows.

python setup.py install --prefix="\Temp\Python"

The installation base is defined by the --prefix option; the --exec-prefix option is not supported under Windows. Files are installed as follows:

Type of file	Installation Directory	Override option
pure module distribution	prefix	--install-purelib
non-pure module distribution	prefix	--install-platlib
scripts	prefix\Scripts	--install-scripts
data	prefix\Data	--install-data