安装Python模块（旧版）¶
- 作者:
Greg Ward
备注
整个 distutils 包已被弃用并将在 Python 3.12 中被移除。 此文档仅保留作参考，并将随包一起被移除。 更多信息请参阅 有什么新变化 条目。
参见
- 安装 Python 模块
最新的模块安装文档。对于常规Python使用，你几乎肯定像使用该文档而非这个。
备注
这篇文档是历史遗留文档，在 https://setuptools.readthedocs.io/en/latest/setuptools.html 上的 setuptools 文档独立涵盖此处包含的所有相关信息之后，将不再单独作为正式文档保留。
备注
本指南仅介绍构建和分发扩展的基本工具，这些扩展是作为此Python版本的一部分提供的。 第三方工具提供更易于使用和更安全的替代方案。有关详细信息，请参阅 Python 打包用户指南中的 快速推荐部分 。
概述¶
在Python 2.0中，distutils API 首次被添加到标准库中。这向Linux发行版维护者提供了一个将Python项目转换为发行版软件包的标准方法，以及向系统管理员们提供了直接将这些软件包安装到目标系统的标准方法。
自从很多年前 Python 2.0 发布，将构建系统和包安装器与语言运行时的释放循环紧密连接在一起产生了很多问题。现在推荐做法是在项目中使用 pip 包安装器和 setuptools 构建系统，而不是直接使用 distutils。
请参阅 安装 Python 模块 和 分发 Python 模块 了解更多细节。
这个旧文档将被保留，至到我们相信 setuptools 覆盖了所有内容。
基于 distutils 的源代码分发¶
如果你下载了一个模块源代码发布包，你可以很快地确定它是否按标准方式，即使用 Distutils 进行打包和分发。 首先，发布包的名称和版本号将在已下载归档文件的名称中明确显示，例如 foo-1.0.tar.gz 或 widget-0.9.7.zip。 然后，归档文件将被解包为类似名称的目录: foo-1.0 或 widget-0.9.7。 此外，发布包将包含一个安装脚本 setup.py，以及一个名为 README.txt 或是 README 的文件，它应当写明构建和安装模块发布包的方式是简单地在终端中运行一条命令:
python setup.py install
Windows 用户应该使用命令提示符来运行命令():
setup.py install
如果这些事情都属实，那么您已经了解了如何构建和安装您已经下载的模块：只需运行如上的命令。除非您需要以非常规方式安装或者定制构建过程，您其实不需要本文档。更进一步说，以上命令就是您可以从文档中获得的全部。
标准构建及安装¶
正如 基于 distutils 的源代码分发 中所描述的那样，通过 Distutils 构建和安装发行的模块常常只需要在终端执行一个简单的命令。
python setup.py install
平台差异¶
您应当总是在分发文件的根目录处运行设置的命令，比如，模块分发的源代码最高的子目录。例如，如果您刚刚在 Unix 操作系统上下载了一个模块分发的源代码，您需要做的事：
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
在 Windows 上，你下载到的可能是 foo-1.0.zip。 如果你将归档文件下载到 C:\Temp，则它将被解包至 C:\Temp\foo-1.0；你可以使用带有图形用户界面的归档管理器（如 WinZip）或命令行工具（如 unzip 或 pkunzip 等）来解包归档文件。 然后，打开一个命令行提示符窗口并运行:
cd c:\Temp\foo-1.0
python setup.py install
拆分任务¶
运行 setup.py install 会在一次运行中构建并安装所有模块。如果你更喜欢逐步进行——特别是当你想自定义构建过程，或者遇到问题时，这尤其有用——你可以使用安装脚本每次只做一件事。当构建和安装由不同的用户完成时，这特别有帮助——例如，你可能想构建一个模块发布包并将其交给系统管理员进行安装（或者使用超级用户权限自己完成）。
例如，你可以通过调用两次安装脚本，在第一步中构建所有内容，然后在第二步中安装所有内容:
python setup.py build
python setup.py install
如果你这样做，你会注意到运行 install 命令会首先运行 build 命令，而在这种情况下，它会很快发现自己无事可做，因为 build 目录中的所有内容都是最新的。
如果你所做的只是安装从网上下载的模块，你可能不需要经常使用这种拆分步骤的能力，但对于更高级的任务来说，它非常方便。如果你开始分发自己的 Python 模块和扩展，你将单独运行许多独立的 Distutils 命令。
构建的工作原理¶
如上所述，build 命令负责将要安装的文件放入一个 构建目录 中。默认情况下，这是发布包根目录下的 build；如果你非常关注速度，或者希望保持源代码树的整洁，可以使用 --build-base 选项更改构建目录。例如:
python setup.py build --build-base=/path/to/pybuild/foo-1.0
（或者你也可以通过在系统或个人 Distutils 配置文件中使用指令来永久执行此操作；请参阅 Distutils 配置文件Configuration Files 一节。）通常情况下，这是没有必要的。
构建树的默认布局如下:
--- build/ --- lib/
or
--- build/ --- lib.<plat>/
temp.<plat>/
其中 <plat> 会展开为当前操作系统/硬件平台和 Python 版本的简短描述。第一种形式只有一个 lib 目录，用于“纯模块发布包”——即仅包含纯 Python 模块的模块发布包。如果模块发布包包含任何扩展（用 C/C++ 编写的模块），则使用带有两个 <plat> 目录的第二种形式。在这种情况下，temp.plat 目录保存由编译/链接过程生成的临时文件，这些文件实际上不会被安装。无论哪种情况，lib (或 lib.plat) 目录都包含所有将被安装的 Python 模块（纯 Python 模块和扩展模块）。
在未来，将会添加更多目录来处理 Python 脚本、文档、二进制可执行文件，以及处理安装 Python 模块和应用程序工作所需的任何其他内容。
安装的工作原理¶
在 build 命令运行之后（无论你是显式运行它，还是由 install 命令为你运行），install 命令的工作相对简单：它所要做的只是将 build/lib (或 build/lib.plat) 下的所有内容复制到你选择的安装目录中。
如果你没有选择安装目录——即如果你只运行 setup.py install ——那么 install 命令会将模块安装到第三方 Python 模块的标准位置。此位置因平台以及你构建/安装 Python 本身的方式而异。在 Unix（以及同样基于 Unix 的 macOS）上，它还取决于正在安装的模块发布包是纯 Python 的还是包含扩展的（“非纯的”）：
平台 |
标准安装位置 |
默认值 |
备注 |
|---|---|---|---|
（单一）Unix |
|
|
(1) |
（类）Unix |
|
|
(1) |
Windows |
|
|
(2) |
注释：
大多数 Linux 发行版都将 Python 作为系统的标准部分包含在内，因此在 Linux 上
prefix和exec-prefix通常都是/usr。如果你在 Linux（或任何类 Unix 系统）上自己构建 Python，则默认的prefix和exec-prefix是/usr/local。在 Python 1.6a1、1.5.2 及更早版本下，Windows 上的默认安装目录是
C:Program FilesPython。
prefix 和 exec-prefix 代表 Python 安装到的目录，以及它在运行时查找其库的目录。它们在 Windows 下总是相同的，而在 Unix 和 macOS 下也往往是相同的。你可以通过以交互模式运行 Python 并输入几个简单的命令，来弄清楚你的 Python 安装对 prefix 和 exec-prefix 使用的值。在 Unix 下，只需在 shell 提示符下输入 python。在 Windows 下，选择 。启动解释器后，即可在提示符下输入 Python 代码。例如，在我的 Linux 系统上，我输入如下所示的三条 Python 语句，并得到所示的输出，从而找出我的 prefix 和 exec-prefix：
Python 2.4 (#26, Aug 7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'
本文档中还使用了其他几个占位符：X.Y 代表 Python 的版本，例如 3.2；abiflags 将被替换为 sys.abiflags 的值，或者对于未定义 ABI 标志的平台则替换为空字符串；distname 将被替换为正在安装的模块发布包的名称。路径中的点号和大小写很重要；例如，在 UNIX 上使用 python3.2 的值在 Windows 上通常会使用 Python32。
如果你不想将模块安装到标准位置，或者你没有在该位置写入的权限，那么你需要阅读 可选安装形式 一节中有关替代安装的内容。如果你想更深入地自定义安装目录，请参阅有关自定义安装的 自定义安装 一节。
可选安装形式¶
通常，有必要或希望将模块安装到第三方 Python 模块标准位置以外的位置。例如，在 Unix 系统上，你可能没有向标准第三方模块目录写入的权限。或者你可能希望在将某个模块作为本地 Python 安装的标准部分之前先试用一下它。在升级已经存在的发布包时尤其如此：在实际升级之前，你希望确保现有的脚本库仍然可以与新版本一起正常工作。
Distutils 的 install 命令旨在使将模块发布包安装到替代位置变得简单而轻松。其基本思想是你为安装提供一个基准目录，然后 install 命令在此基准目录下选择一组目录（称为 安装方案）来安装文件。具体细节因平台而异，因此请阅读以下适用于你的章节。
请注意，各种替代安装方案是互斥的：你可以传递 --user，或者 --home，或者 --prefix 和 --exec-prefix，或者 --install-base 和 --install-platbase，但你不能混用这些组合。
可选安装形式：用户方案¶
此方案被设计为针对没有全局 site-packages 目录写入权限或不想安装到该目录的用户的最便捷解决方案。 它可以通过一个简单的选项来启用:
python setup.py install --user
文件将被安装到 site.USER_BASE （以下简称 userbase）的子目录中。此方案将纯 Python 模块和扩展模块安装在同一位置（也称为 site.USER_SITE）。以下是包括 macOS 在内的 UNIX 所使用的值：
文件类型 |
安装目录 |
|---|---|
模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
以下是Windows上使用的值：
文件类型 |
安装目录 |
|---|---|
模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
与下面描述的其他方案相比，使用此方案的优势在于，用户 site-packages 目录在正常情况下总是包含在 sys.path 中（更多信息请参阅 site），这意味着在运行 setup.py 脚本之后无需执行额外的步骤即可完成安装。
build_ext 命令也有一个 --user 选项，用于将 userbase/include 添加到编译器的头文件搜索路径中，并将 userbase/lib 添加到编译器的库搜索路径以及共享 C 库的运行时搜索路径 (rpath) 中。
可选安装形式：家目录方案¶
“主方案”背后的理念是你可以构建并维护个人的 Python 模块集。 该方案的名称源自 Unix 上“主目录”的概念，因为通常 Unix 用户会将其主目录的布局设置为与 /usr/ 或 /usr/local/ 相似。 任何人都可以使用该方案，无论其安装的操作系统是什么。
安装一个新的模块发布包非常简单
python setup.py install --home=<dir>
其中你可以为 --home 选项提供任何你喜欢的目录。在 Unix 上，懒得打字的人可以只输入一个波浪号 (~)；install 命令会将其展开为你的主目录:
python setup.py install --home=~
为了让 Python 找到使用此方案安装的发布包，你可能需要 修改 Python 的搜索路径，或者编辑 sitecustomize （参阅 site）以调用 site.addsitedir() 或直接编辑 sys.path。
--home 选项定义了安装基准目录。文件将被安装到安装基准目录下的以下目录中，如下所示：
文件类型 |
安装目录 |
|---|---|
模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
（如果你是使用 Windows 请将斜杠替换为反斜杠。）
可选安装形式：Unix（前缀方案）¶
“前缀方案”适用于当你希望使用一个 Python 安装程序来执行构建/安装（即运行 setup 脚本），但需要将模块安装到另一个 Python 安装版（或看起来类似于另一个 Python 安装版）的第三方模块目录中的情况。 如果这听起来有点不寻常，确实如此 --- 这就是为什么要先介绍用户和主目录方案的原因。 然而，至少有两种已知的情况会用到前缀方案。
首先，考虑到许多 Linux 发行版将 Python 放在 /usr 中，而不是更传统的 /usr/local 中。这是完全恰当的，因为在这些情况下，Python 是“系统”的一部分，而不是本地附加组件。但是，如果你是从源代码安装 Python 模块，你可能会希望将它们放在 /usr/local/lib/python2.X 中，而不是 /usr/lib/python2.X 中。这可以通过以下命令完成
/usr/bin/python setup.py install --prefix=/usr/local
另一种可能性是网络文件系统，其中用于写入远程目录的名称与用于读取它的名称不同：例如，作为 /usr/local/bin/python 访问的 Python 解释器可能会在 /usr/local/lib/python2.X 中搜索模块，但这些模块必须安装到（比方说） /mnt/@server/export/lib/python2.X 中。这可以通过以下命令完成
/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
无论哪种情况，--prefix 选项定义了安装基准目录，而 --exec-prefix 选项定义了特定于平台的安装基准目录，该目录用于存放特定于平台的文件。（目前，这只意味着非纯模块发布包，但可以扩展到 C 库、二进制可执行文件等。）如果未提供 --exec-prefix，则默认为 --prefix。文件的安装位置如下：
文件类型 |
安装目录 |
|---|---|
Python 模块 |
|
扩展模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
并不要求 --prefix 或 --exec-prefix 实际上指向一个替代的 Python 安装；如果上面列出的目录尚不存在，则会在安装时创建它们。
顺便说一句，前缀方案之所以重要的真正原因仅仅在于标准 Unix 安装使用了前缀方案，只不过其 --prefix 和 --exec-prefix 是由 Python 本身作为 sys.prefix 和 sys.exec_prefix 提供的。因此，你可能认为自己永远不会使用前缀方案，但每次你在不带任何其他选项的情况下运行 python setup.py install 时，你都在使用它。
请注意，将扩展安装到替代的 Python 安装中不会影响这些扩展的构建方式：具体而言，在编译扩展时，将使用与用于运行安装脚本的 Python 解释器一起安装的 Python 头文件（Python.h 及其同类）。你有责任确保用于运行以此方式安装的扩展的解释器与用于构建它们的解释器兼容。做到这一点的最佳方法是确保这两个解释器是相同版本的 Python（可能是不同的构建版本，或者是相同构建版本的副本）。（当然，如果你的 --prefix 和 --exec-prefix 甚至没有指向替代的 Python 安装，这就无关紧要了。）
可选安装形式：Windows（前缀方案）¶
Windows 没有用户主目录的概念，而且由于 Windows 下的标准 Python 安装比 Unix 下更简单，因此传统上一直使用 --prefix 选项在 Windows 上的单独位置安装附加包。
python setup.py install --prefix="\Temp\Python"
以将模块安装到当前驱动器上的 TempPython 目录中。
安装基准目录由 --prefix 选项定义；Windows 下不支持 --exec-prefix 选项，这意味着纯 Python 模块和扩展模块会安装到同一位置。文件的安装位置如下：
文件类型 |
安装目录 |
|---|---|
模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
自定义安装¶
有时候，可选安装形式 一节中描述的替代安装方案并不能满足你的需求。你可能只想调整一两个目录，同时将其余所有内容保留在同一个基准目录下，或者你可能想完全重新定义安装方案。无论哪种情况，你都是在创建一个 自定义安装方案。
要创建自定义安装方案，你可以从一种替代方案开始，并使用以下选项覆盖用于各种类型文件的部分安装目录：
文件类型 |
覆盖选项 |
|---|---|
Python 模块 |
|
扩展模块 |
|
所有模块 |
|
脚本 |
|
数据 |
|
C 头文件 |
|
这些覆盖选项可以是相对路径、绝对路径，或者根据某个安装基准目录显式定义。（有两个安装基准目录，它们通常是相同的——只有当你使用 Unix“前缀方案”并提供不同的 --prefix 和 --exec-prefix 选项时，它们才会不同；使用 --install-lib 将覆盖为 --install-purelib 和 --install-platlib 计算或给定的值，推荐用于不区分 Python 模块和扩展模块的方案。）
例如，假设你正在 Unix 下将一个模块发布包安装到你的主目录中——但你希望脚本放到 ~/scripts 而不是 ~/bin 中。正如你所料，你可以使用 --install-scripts 选项覆盖此目录；在这种情况下，提供相对路径是最合理的，它将相对于安装基准目录（在本例中即你的主目录）进行解释:
python setup.py install --home=~ --install-scripts=scripts
另一个 Unix 示例：假设你的 Python 安装在构建和安装时使用了前缀 /usr/local/python，因此在标准安装下，脚本最终会放在 /usr/local/python/bin 中。如果你希望它们改为放在 /usr/local/bin 中，可以为 --install-scripts 选项提供这个绝对目录:
python setup.py install --install-scripts=/usr/local/bin
（这会使用“前缀方案”执行安装，其中前缀是你的 Python 解释器安装时所使用的任何前缀——在本例中为 /usr/local/python。）
如果你在 Windows 上维护 Python，你可能希望第三方模块位于 prefix 的子目录中，而不是直接位于 prefix 本身中。这几乎和自定义脚本安装目录一样简单——你只需要记住有两种类型的模块需要考虑，即 Python 模块和扩展模块，它们可以很方便地通过一个选项同时进行控制:
python setup.py install --install-lib=Site
指定的安装目录是相对于 prefix 的。当然，你还必须确保此目录位于 Python 的模块搜索路径中，例如将 .pth 文件放在站点目录中（参阅 site）。请参阅 修改 Python 的搜索路径 一节以了解如何修改 Python 的搜索路径。
如果你想定义一个完整的安装方案，你只需提供所有的安装目录选项。推荐的做法是提供相对路径；例如，如果你想将所有与 Python 模块相关的文件维护在主目录下的 python 目录中，并且希望为你使用主目录的每个平台设置一个单独的目录，你可以定义如下安装方案:
python setup.py install --home=~ \
--install-purelib=python/lib \
--install-platlib=python/lib.$PLAT \
--install-scripts=python/scripts
--install-data=python/data
或者，等价于
python setup.py install --home=~/python \
--install-purelib=lib \
--install-platlib='lib.$PLAT' \
--install-scripts=scripts
--install-data=data
$PLAT 不（一定）是一个环境变量——当 Distutils 解析你的命令行选项时，它会像解析配置文件时一样展开该变量。
显然，每次安装新的模块发布包时都指定整个安装方案会非常繁琐。因此，你可以将这些选项放入你的 Distutils 配置文件中（参阅 Distutils 配置文件Configuration Files 一节）：
[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
或者，等价于，
[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
请注意，如果你在运行安装脚本时提供了不同的安装基准目录，那么这两者是 不 等价的。例如，
python setup.py install --install-base=/tmp
在第一种情况下会将纯模块安装到 /tmp/python/lib 中，而在第二种情况下则会安装到 /tmp/lib 中。（对于第二种情况，你可能希望提供一个 /tmp/python 作为安装基准目录。）
你可能已经注意到示例配置文件输入中使用了 $HOME 和 $PLAT。这些是 Distutils 配置变量，它们与环境变量非常相似。事实上，在具有环境变量概念的平台上，你可以在配置文件中使用环境变量，但 Distutils 另外还定义了一些可能不在你的环境中的额外变量，例如 $PLAT。（当然，在没有环境变量的系统上，例如 Mac OS 9，Distutils 提供的配置变量是你唯一可以使用的变量。）详见 Distutils 配置文件Configuration Files 一节。
备注
当 虚拟环境 被激活时，所有 distutils 配置文件中任何更改安装路径的选项都将被忽略，以防止无意中将项目安装到虚拟环境之外。
修改 Python 的搜索路径¶
当 Python 解释器执行 import 语句时，它会沿着搜索路径搜索 Python 代码和扩展模块。当构建解释器时，路径的默认值会被配置到 Python 二进制文件中。你可以通过导入 sys 模块并打印 sys.path 的值来确定该路径。
$ python
Python 2.2 (#11, Oct 3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
'/usr/local/lib/python2.3/site-packages']
>>>
sys.path 中的空字符串代表当前工作目录。
本地安装包的预期惯例是将它们放在 .../site-packages/ 目录中，但你可能希望将 Python 模块安装到某个任意目录中。例如，你的站点可能有一个惯例，即将与 Web 服务器相关的所有软件保存在 /www 下。附加的 Python 模块随后可能属于 /www/python，而为了导入它们，必须将此目录添加到 sys.path 中。有几种不同的方法可以添加该目录。
最方便的方法是将一个路径配置文件添加到已经在 Python 路径上的目录中，通常是添加到 .../site-packages/ 目录中。路径配置文件的扩展名为 .pth，每行必须包含一个将被追加到 sys.path 的单一路径。（因为新路径是追加到 sys.path 的，所以添加目录中的模块不会覆盖标准模块。这意味着你不能使用此机制来安装标准模块的修复版本。）
路径可以是绝对路径或相对路径，如果是相对路径，则相对于包含 .pth 文件的目录。更多信息请参阅 site 模块的文档。
一种稍显不便的方法是编辑 Python 标准库中的 site.py 文件，并修改 sys.path。当执行 Python 解释器时会自动导入 site.py，除非提供了 -S 开关来抑制此行为。因此，你可以简单地编辑 site.py 并向其中添加两行：
import sys
sys.path.append('/www/python/')
但是，如果你重新安装相同的次要版本的 Python（例如从 2.2 升级到 2.2.2 时），site.py 将被原装版本覆盖。你必须记住它曾被修改过，并在执行安装之前保存一份副本。
有两个环境变量可以修改 sys.path。 PYTHONHOME 为 Python 安装的前缀设置一个替代值。例如，如果将 PYTHONHOME 设置为 /www/python，则搜索路径将被设置为 ['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]。
PYTHONPATH 变量可以设置为一个路径列表，这些路径将被添加到 sys.path 的开头。例如，如果将 PYTHONPATH 设置为 /www/python:/opt/py，则搜索路径将以 ['/www/python', '/opt/py'] 开头。（请注意，目录必须存在才能被添加到 sys.path 中；site 模块会移除不存在的路径。）
最后，sys.path 只是一个常规的 Python 列表，因此任何 Python 应用程序都可以通过添加或删除条目来修改它。
Distutils 配置文件Configuration Files¶
如上所述，你可以使用 Distutils 配置文件来记录任何 Distutils 选项的个人或站点偏好设置。也就是说，任何命令的任何选项都可以存储在两个或三个（取决于你的平台）配置文件之一中，在解析命令行之前会先查阅这些配置文件。这意味着配置文件将覆盖默认值，而命令行反过来又会覆盖配置文件。此外，如果多个配置文件适用，则“较早”文件中的值会被“较晚”文件中的值覆盖。
配置文件的位置和名称¶
配置文件的名称和位置因平台而略有不同。在 Unix 和 macOS 上，这三个配置文件（按其处理顺序）为：
文件类型 |
位置和文件名 |
备注 |
|---|---|---|
system |
|
(1) |
personal |
|
(2) |
local |
|
(3) |
而在 Windows 中，配置文件为:
文件类型 |
位置和文件名 |
备注 |
|---|---|---|
system |
|
(4) |
personal |
|
(5) |
local |
|
(3) |
在所有平台上，都可以通过传递 --no-user-cfg 选项来临时禁用“个人”配置文件。
注释：
严格来说，系统范围的配置文件位于安装 Distutils 的目录中；在 Unix 上的 Python 1.6 及更高版本下，该位置如图所示。对于 Python 1.5.2，Distutils 通常会安装到
prefix/lib/python1.5/site-packages/distutils，因此在 Python 1.5.2 下系统配置文件应该放在那里。在 Unix 上，如果未定义
HOME环境变量，则将使用标准pwd模块中的getpwuid()函数来确定用户的主目录。这是由 Distutils 使用的os.path.expanduser()函数完成的。即在当前目录（通常是安装脚本所在的位置）中。
（另请参阅注释 (1)。）在 Python 1.6 及更高版本下，Python 的默认“安装前缀”是
C:Python，因此系统配置文件通常是C:PythonLibdistutilsdistutils.cfg。在 Python 1.5.2 下，默认前缀是C:Program FilesPython，并且 Distutils 不是标准库的一部分——因此在 Windows 下的标准 Python 1.5.2 安装中，系统配置文件将是C:Program FilesPythondistutilsdistutils.cfg。在 Windows 上，如果未定义
HOME环境变量，则会依次尝试USERPROFILE、HOMEDRIVE和HOMEPATH。这是由 Distutils 使用的os.path.expanduser()函数完成的。
配置文件的语法¶
Distutils 配置文件都具有相同的语法。配置文件被分为若干个小节。每个 Distutils 命令都有一个小节，外加一个用于影响每个命令的全局选项的 global 小节。每个小节由每行一个选项组成，指定为 option=value。
例如，下面是一个完整的配置文件，它只是强制所有命令默认以安静模式运行：
[global]
verbose=0
如果将此文件安装为系统配置文件，它将影响当前系统上任何用户对任何 Python 模块发布包的所有处理。如果将其安装为你的个人配置文件（在支持它们的系统上），它将仅影响由你处理的模块发布包。如果将其用作特定模块发布包的 setup.cfg，则它仅影响该发布包。
你可以通过以下配置覆盖默认的“构建基准”目录，并使 build* 命令始终强制重新构建所有文件：
[build]
build-base=blib
force=1
这对应于命令行参数
python setup.py build --build-base=blib --force
区别在于，在命令行中包含 build 命令意味着该命令将被运行。而在配置文件中包含特定命令并没有这样的含义；它只是意味着如果运行该命令，配置文件中的选项将会生效。（或者，如果运行从该命令派生值的其他命令，它们将使用配置文件中的值。）
你可以使用 --help 选项找出任何命令的完整选项列表，例如:
python setup.py build --help
并且你可以通过在不带命令的情况下使用 --help 来找出全局选项的完整列表:
python setup.py --help
另请参阅“分发 Python 模块”手册中的“参考”一节。
构建扩展：提示与技巧¶
只要有可能，Distutils 就会尝试使用由用于运行 setup.py 脚本的 Python 解释器所提供的配置信息。例如，用于编译 Python 的相同编译器和链接器标志也将用于编译扩展。通常这会工作得很好，但在复杂的情况下这可能是不合适的。本节讨论如何覆盖通常的 Distutils 行为。
调整编译器/链接器标志¶
编译用 C 或 C++ 编写的 Python 扩展有时需要为编译器和链接器指定自定义标志，以便使用特定的库或生成特殊类型的目标代码。如果该扩展尚未在你的平台上进行过测试，或者你正在尝试交叉编译 Python，情况尤其如此。
在最一般的情况下，扩展作者可能已经预见到编译扩展会很复杂，并提供了一个供你编辑的 Setup 文件。这通常只有在模块发布包包含许多独立的扩展模块，或者它们通常需要精心设计的编译器标志集才能工作时才会这样做。
如果存在 Setup 文件，则会对其进行解析以获取要构建的扩展列表。 Setup 中的每一行描述一个单独的模块。每行的结构如下:
module ... [sourcefile ...] [cpparg ...] [library ...]
让我们依次检查每个字段。
module 是要构建的扩展模块的名称，应该是一个有效的 Python 标识符。你不能仅仅为了重命名模块而更改它（那样还需要编辑源代码），因此应该保持原样。
sourcefile 是任何可能是源代码文件的内容，至少从文件名判断是如此。以
.c结尾的文件名假定是用 C 编写的，以.C、.cc和.c++结尾的文件名假定是 C++，而以.m或.mm结尾的文件名假定是用 Objective C 编写的。cpparg 是 C 预处理器的参数，是任何以
-I、-D、-U或-C开头的内容。library 是任何以
.a结尾或以-l或-L开头的内容。
如果特定平台需要你平台上的某个特殊库，你可以通过编辑 Setup 文件并运行 python setup.py build 来添加它。例如，如果由以下行定义的模块
foo foomodule.c
在你的平台上必须与数学库 libm.a 链接，只需向该行添加 -lm 即可:
foo foomodule.c -lm
旨在提供给编译器或链接器的任意开关可以通过 -Xcompiler arg 和 -Xlinker arg 选项提供:
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
-Xcompiler 和 -Xlinker 之后的下一个选项将被追加到相应的命令行中，因此在上面的示例中，编译器将被传递 -o32 选项，而链接器将被传递 -shared 选项。如果编译器选项需要参数，则必须提供多个 -Xcompiler 选项；例如，要传递 -x c++，Setup 文件必须包含 -Xcompiler -x -Xcompiler c++。
编译器标志也可以通过设置 CFLAGS 环境变量来提供。如果设置了该变量，CFLAGS 的内容将被添加到 Setup 文件中指定的编译器标志中。
在 Windows 上使用非 Microsoft 编辑器¶
Borland/CodeGear C++¶
本小节描述了将 Distutils 与 Borland C++ 编译器 5.5 版结合使用所需的步骤。首先你必须知道，Borland 的目标文件格式 (OMF) 与你可以从 Python 或 ActiveState 网站下载的 Python 版本所使用的格式不同。（Python 是用 Microsoft Visual C++ 构建的，它使用 COFF 作为目标文件格式。）由于这个原因，你必须将 Python 的库 python25.lib 转换为 Borland 格式。你可以按如下方式执行此操作：
coff2omf python25.lib python25_bcpp.lib
coff2omf 程序随 Borland 编译器一起提供。文件 python25.lib 位于你的 Python 安装的 Libs 目录中。如果你的扩展使用了其他库 (zlib 等)，你也必须转换它们。
转换后的文件必须与常规库位于同一目录中。
Distutils 是如何设法使用这些更改了名称的库的？如果扩展需要一个库（例如 foo），Distutils 首先会检查是否能找到带有后缀 _bcpp 的库（例如 foo_bcpp.lib），然后使用这个库。如果找不到这样一个特殊的库，它就会使用默认名称 (foo.lib)。 [1]
要让 Distutils 使用 Borland C++ 编译你的扩展，你现在必须输入:
python setup.py build --compiler=bcpp
如果你想默认使用 Borland C++ 编译器，可以在 Distutils 的个人或系统范围的配置文件中指定它（参阅 Distutils 配置文件Configuration Files 一节）。
参见
- C++Builder Compiler
有关 Borland 发布的免费 C++ 编译器的信息，包括下载页面的链接。
- Creating Python Extensions Using Borland's Free Compiler
介绍如何使用 Borland 发布的免费命令行方式 C++ 编译器构建 Python 的文档。
GNU C / Cygwin / MinGW¶
本节描述了将 Distutils 与 Cygwin 和 MinGW 发行版中的 GNU C/C++ 编译器结合使用所需的步骤。 [2] 对于使用 Cygwin 构建的 Python 解释器，无需执行以下任何步骤，一切都应该能够正常工作。
并非所有扩展都可以使用 MinGW 或 Cygwin 进行构建，但许多扩展都可以。最可能无法工作的扩展是那些使用 C++ 或依赖 Microsoft Visual C 扩展的模块。
要让 Distutils 使用 Cygwin 编译你的扩展，你必须输入:
python setup.py build --compiler=cygwin
而对于处于 no-cygwin 模式的 Cygwin [3] 或对于 MinGW，请输入:
python setup.py build --compiler=mingw32
如果你想默认使用这些选项/编译器中的任何一个，你应该考虑将其写入你的 Distutils 个人或系统范围的配置文件中（参阅 Distutils 配置文件Configuration Files 一节）。
旧版 Python 和 MinGW¶
以下说明仅适用于你正在将低于 2.4.1 版本的 Python 与低于 3.0.0 版本的 MinGW (带有 binutils-2.13.90-20030111-1) 配合使用的情况。
这些编译器需要一些特殊的库。这项任务比 Borland 的 C++ 更复杂，因为没有程序可以转换该库。首先，你必须创建一个由 Python DLL 导出的符号列表。（你可以在 https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/ 找到一个用于完成此任务的优秀程序）。
pexports python25.dll >python25.def
已安装的 python25.dll 的位置取决于安装选项以及 Windows 的版本和语言。在“仅为我”安装中，它将出现在安装目录的根目录下。在共享安装中，它将位于系统目录中。
然后，你可以根据这些信息为 gcc 创建一个导入库。
/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
生成的库必须放在与 python25.lib 相同的目录中。（应该是你的 Python 安装目录下的 libs 目录。）
如果你的扩展使用了其他库 (zlib 等)，你可能也必须对它们进行转换。转换后的文件必须与常规库位于相同的目录中。
参见
- 在 MS Windows 平台上使用 MinGW 构建 Python 模块
针对 MinGW 环境生成必要的库的相关信息
备注