5 Distutils Configuration Files

As mentioned above, you can use Distutils configuration files to record personal or site preferences for any Distutils options. That is, any option to any command can be stored in one of two or three (depending on your platform) configuration files, which will be consulted before the command-line is parsed. This means that configuration files will override default values, and the command-line will in turn override configuration files. Furthermore, if multiple configuration files apply, values from ``earlier'' files are overridden by ``later'' files.

5.1 Location and names of config files

The names and locations of the configuration files vary slightly across platforms. On Unixand Mac OS X, the three configuration files (in the order they are processed) are:

Type of file	Location and filename	Notes
system	prefix/lib/pythonver/distutils/distutils.cfg	(1)
personal	$HOME/.pydistutils.cfg	(2)
local	setup.cfg	(3)

And on Windows, the configuration files are:

Type of file	Location and filename	Notes
system	prefix\Lib\distutils\distutils.cfg	(4)
personal	%HOME%\pydistutils.cfg	(5)
local	setup.cfg	(3)

Notes:

(1): Strictly speaking, the system-wide configuration file lives in the directory where the Distutils are installed; under Python 1.6 and later on Unix, this is as shown. For Python 1.5.2, the Distutils will normally be installed to prefix/lib/python1.5/site-packages/distutils, so the system configuration file should be put there under Python 1.5.2.
(2): On Unix, if the HOME environment variable is not defined, the user's home directory will be determined with the getpwuid() function from the standard pwd module.
(3): I.e., in the current directory (usually the location of the setup script).
(4): (See also note (1).) Under Python 1.6 and later, Python's default ``installation prefix'' is C:\Python, so the system configuration file is normally C:\Python\Lib\distutils\distutils.cfg. Under Python 1.5.2, the default prefix was C:\Program Files\Python, and the Distutils were not part of the standard library--so the system configuration file would be C:\Program Files\Python\distutils\distutils.cfg in a standard Python 1.5.2 installation under Windows.
(5): On Windows, if the HOME environment variable is not defined, no personal configuration file will be found or used. (In other words, the Distutils make no attempt to guess your home directory on Windows.)

5.2 Syntax of config files

The Distutils configuration files all have the same syntax. The config files are grouped into sections. There is one section for each Distutils command, plus a global section for global options that affect every command. Each section consists of one option per line, specified as option=value.

For example, the following is a complete config file that just forces all commands to run quietly by default:

[global]
verbose=0

If this is installed as the system config file, it will affect all processing of any Python module distribution by any user on the current system. If it is installed as your personal config file (on systems that support them), it will affect only module distributions processed by you. And if it is used as the setup.cfg for a particular module distribution, it affects only that distribution.

You could override the default ``build base'' directory and make the build* commands always forcibly rebuild all files with the following:

[build]
build-base=blib
force=1

which corresponds to the command-line arguments

python setup.py build --build-base=blib --force

except that including the build command on the command-line means that command will be run. Including a particular command in config files has no such implication; it only means that if the command is run, the options in the config file will apply. (Or if other commands that derive values from it are run, they will use the values in the config file.)

You can find out the complete list of options for any command using the --help option, e.g.:

python setup.py build --help

and you can find out the complete list of global options by using --help without a command:

python setup.py --help

See also the ``Reference'' section of the ``Distributing Python Modules'' manual.

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