7.4 The Distribution Utilities (distutils)

Python modules, extensions, and applications can be packaged and distributed in several forms:

Compressed archive files

Generally .zip for Windows and .tar.gz or .tgz for Unix-based systems, but both forms are portable

Self-unpacking or self-installing executables

Normally .exe for Windows

Platform-specific installers

For example, .msi on Windows, .rpm and .srpm on Linux, and .deb on Debian GNU/Linux

When you distribute a package as a self-installing executable or platform-specific installer, a user can then install the package simply by running the installer. How to run such an installer program depends on the platform, but it no longer matters what language the program was written in.

When you distribute a package as an archive file or as an executable that unpacks but does not install itself, it does matter that the package was coded in Python. In this case, the user must first unpack the archive file into some appropriate directory, say C:\Temp\MyPack on a Windows machine or ~/MyPack on a Unix-like machine. Among the extracted files there should be a script, conventionally named setup.py, that uses the Python facility known as the distribution utilities (package distutils). The distributed package is then almost as easy to install as a self-installing executable would be. The user opens a command-prompt window and changes to the directory into which the archive is unpacked. Then the user runs, for example:

C:\Temp\MyPack> python setup.py install

The setup.py script, run with this install command, installs the package as a part of the user's Python installation, according to the options specified in the setup script by the package's author. distutils, by default, provides tracing information when the user runs setup.py. Option --quiet, placed right before the install command, hides most details (the user still sees error messages, if any). The following command:

C:\> python setup.py --help

gives help on distutils.

When you are installing a package prepared with distutils, you can, if you wish, exert detailed control over how distutils performs installations. You can record installation options in a text file with extension .cfg, called a config file, so that distutils applies your favorite installation options by default. Such customization can be done on a systemwide basis, for a single user, or even for a single package installation. For example, if you want an installation with minimal amounts of output to be your systemwide default, create the following text file named pydistutils.cfg:

 [global]
quiet=1

Place this file in the same directory in which the distutils package resides. On a typical Python 2.2 installation on Windows, for example, the file is C:\Python22\Lib\distutils\pydistutils.cfg. Chapter 26 provides more information on using distutils to prepare Python modules, packages, extensions, and applications for distribution.