Subsections

 
4 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.

 
4.1 Alternate installation: Unix (the home scheme)

Under Unix, there are two ways to perform an alternate installation. The ``prefix scheme'' is similar to how alternate installation works under Windows and MacOS, but is not necessarily the most useful way to maintain a personal Python library. Hence, we document the more convenient and commonly useful ``home scheme'' first.

The idea behind the ``home scheme'' is that you build and maintain a personal stash of Python modules, probably under your home directory. Installing a new module distribution is as simple as

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

where you can supply any directory you like for the --home option. 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

 
4.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/python1.X rather than /usr/lib/python1.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/python1.X, but those modules would have to be installed to, say, /mnt/@server/export/lib/python1.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/python1.X/site-packages --install-purelib
non-pure module distribution exec-prefix/lib/python1.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 compatibile 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.)

 
4.3 Alternate installation: Windows

Since Windows has no conception of a user's home directory, and since the standard Python installation under Windows is simpler than that under Unix, there's no point in having separate --prefix and --home options. Just use the --prefix option to specify a base directory, e.g.

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

to install modules to the \Temp directory on the current drive.

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

 
4.4 Alternate installation: MacOS

Like Windows, MacOS has no notion of home directories (or even of users), and a fairly simple standard Python installation. Thus, only a --prefix option is needed. It defines the installation base, and files are installed under it as follows:

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

See section 2.1 for information on supplying command-line arguments to the setup script with MacPython.

See About this document... for information on suggesting changes.