Subsections

- 4.1 Alternate installation: Unix (the home scheme)
- 4.2 Alternate installation: Unix (the prefix scheme)
- 4.3 Alternate installation: Windows
- 4.4 Alternate installation: MacOS

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