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''
5.1 Location and names of config files
The names and locations of the configuration files vary slightly across platforms. On Unix, the three configuration files (in the order
they are processed) are:
On Windows, the configuration files are:
And on Mac OS, they are:
- 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/site-packages/python1.5/distutils,
so the system configuration file should be put there under Python 1.5.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.
- I.e., in the current directory (usually the location of the setup script).
- (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.
- 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.)
- (See also notes (1) and (4).) The default installation prefix is just Python:,
so under Python 1.6 and later this is normallyPython:Lib:distutils:distutils.cfg.
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
section for global options that affect every command. Each section consists of one option per
line, specified as
For example, the following is a complete config file that just forces all commands to run
quietly by default:
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
commands always forcibly rebuild all files with the following:
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:
See also the ``Reference'' section of the ``Distributing Python Modules'' manual.