安装 Python 模块（旧版）

作者: 格雷格·沃德

也可以看看

安装 Python 模块: 最新的模块安装文档

本文档从最终用户的角度描述了 Python 分发实用程序（“Distutils”），描述了如何通过构建和安装第三方 Python 模块和扩展来扩展标准 Python 安装的功能。

笔记

本指南仅涵盖作为此版本 Python 的一部分提供的用于构建和分发扩展的基本工具。第三方工具提供更易于使用和更安全的替代方案。有关更多信息，请参阅 Python Packaging User Guide 中的快速建议部分。

简介

尽管 Python 广泛的标准库涵盖了许多编程需求，但经常需要以第三方模块的形式向 Python 安装添加一些新功能。这可能是支持您自己的编程或支持您想要使用且恰好是用 Python 编写的应用程序所必需的。

过去，很少支持将第三方模块添加到现有 Python 安装中。随着 Python 2.0 中 Python Distribution Utilities（简称 Distutils）的引入，这种情况发生了变化。

本文档主要面向需要安装第三方 Python 模块的人员：只需要运行一些 Python 应用程序的最终用户和系统管理员，以及想要向其工具箱添加一些新功能的现有 Python 程序员。您无需了解 Python 即可阅读本文档；将有一些简短的尝试使用 Python 的交互模式来探索您的安装，但仅此而已。如果您正在寻找有关如何分发您自己的 Python 模块以便其他人可以使用它们的信息，请参阅分发 Python 模块（旧版）手册。调试安装脚本也可能很有趣。

最佳案例：简单安装

在最好的情况下，有人会准备好您要安装的模块发行版的特殊版本，该版本专门针对您的平台，并且就像您平台上的任何其他软件一样安装。例如，模块开发人员可能会为 Windows 用户提供一个可执行安装程序，为基于 RPM 的 Linux 系统（Red Hat、SuSE、Mandrake 等）用户提供一个 RPM 包，为基于 Debian 的 Linux 用户提供一个 Debian 包系统等等。

在这种情况下，您将下载适合您平台的安装程序并使用它做一些显而易见的事情：如果它是可执行安装程序就运行它，如果它是 RPM 则运行 rpm --install，等等。您不需要运行 Python 或安装脚本，也不需要编译任何东西——您甚至可能不需要阅读任何说明（尽管这样做总是一个好主意）。

当然，事情不会总是那么容易。您可能对没有适用于您的平台的易于使用的安装程序的模块分发感兴趣。在这种情况下，您必须从模块作者/维护者发布的源代码分发开始。只要模块以标准方式打包，从源代码分发安装并不太难。本文档的大部分内容是关于从标准源代码分发构建和安装模块。

新标准：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，此命令应从命令提示符窗口 (Start ‣ Accessories) 运行：

setup.py install

如果所有这些都是真的，那么您已经知道如何构建和安装刚刚下载的模块：运行上面的命令。除非您需要以非标准方式安装东西或自定义构建过程，否则您实际上并不需要这本手册。或者更确切地说，上述命令是您离开本手册所需的一切。

标准构建和安装

如新标准：Distutils 部分所述，使用 Distutils 构建和安装模块分发通常是从终端运行的一个简单命令：

python setup.py install

平台变化

您应该始终从发行版根目录运行 setup 命令，即模块源分发解包到的顶级子目录。例如，如果您刚刚将模块源代码分发 foo-1.0.tar.gz 下载到 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 目录是最新的。

如果您所做的只是安装从 'net 下载的模块，您可能不需要这种经常分解事物的能力，但它对于更高级的任务非常方便。如果您开始分发自己的 Python 模块和扩展，您将自行运行许多单独的 Distutils 命令。

建筑如何运作

如上所述，build 命令负责将要安装的文件放入 构建目录 。默认情况下，这是分布根目录下的 build；如果您过分关注速度，或者想要保持源代码树的原始状态，您可以使用 --build-base 选项更改构建目录。例如：

python setup.py build --build-base=/path/to/pybuild/foo-1.0

（或者，您可以使用系统或个人 Distutils 配置文件中的指令永久执行此操作；请参阅部分 Distutils 配置文件。）通常，这不是必需的。

构建树的默认布局如下：

--- 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 的 Mac OS X）上，它还取决于所安装的模块发行版是纯 Python 还是包含扩展（“非纯”）：

平台	标准安装位置	默认值	提示
Unix（纯）	`prefix/lib/pythonX.Y/site-packages`	`/usr/local/lib/pythonX.Y/site-packages`	(1)
Unix（非纯）	`exec-prefix/lib/pythonX.Y/site-packages`	`/usr/local/lib/pythonX.Y/site-packages`	(1)
Windows	`prefix\Lib\site-packages`	`C:\PythonXY\Lib\site-packages`	(2)

注意：

大多数 Linux 发行版都包含 Python 作为系统的标准部分，因此 prefix 和 exec-prefix 在 Linux 上通常都是 /usr。如果你自己在 Linux（或任何类 Unix 系统）上构建 Python，默认的 prefix 和 exec-prefix 是 /usr/local。
Windows 上的默认安装目录是 C:\Program Files\Python 在 Python 1.6a1、1.5.2 和更早版本下。

prefix 和 exec-prefix 代表 Python 安装到的目录，以及它在运行时找到它的库的位置。它们在 Windows 下总是相同的，并且在 Unix 和 Mac OS X 下经常相同。通过在交互模式下运行 Python 并键入一些简单的命令，您可以找出 Python 安装用于 prefix 和 exec-prefix 的内容。在 Unix 下，只需在 shell 提示符下键入 python。在 Windows 下，选择开始 ‣ 程序 ‣ Python XY ‣ Python（命令行）。解释器启动后，您可以在提示符下键入 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，但您不能从这些组中混音。

替代安装：用户方案

该方案旨在为没有全局站点包目录写入权限或不想安装到其中的用户提供最方便的解决方案。它通过一个简单的选项启用：

python setup.py install --user

文件将被安装到 site.USER_BASE 的子目录中（以下写为 userbase）。该方案将纯 Python 模块和扩展模块安装在同一位置（也称为 site.USER_SITE）。以下是 UNIX 的值，包括 Mac OS X：

文件类型	安装目录
模块	`userbase/lib/pythonX.Y/site-packages`
脚本	`userbase/bin`
数据	`userbase`
C 头文件	`userbase/include/pythonX.Yabiflags/distname`

以下是在 Windows 上使用的值：

文件类型	安装目录
模块	`userbase\PythonXY\site-packages`
脚本	`userbase\PythonXY\Scripts`
数据	`userbase`
C 头文件	`userbase\PythonXY\Include{distname}`

与下面描述的其他方案相比，使用此方案的优点是用户站点包目录在正常情况下始终包含在 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 选项定义安装基础目录。文件安装到安装库下的以下目录如下：

文件类型	安装目录
模块	`home/lib/python`
脚本	`home/bin`
数据	`home`
C 头文件	`home/include/python/distname`

（如果您使用的是 Windows，请在心里用反斜杠替换斜杠。）

替代安装：Unix（前缀方案）

当您希望使用一个 Python 安装来执行构建/安装（即运行安装脚本），但将模块安装到另一个 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 模块	`prefix/lib/pythonX.Y/site-packages`
扩展模块	`exec-prefix/lib/pythonX.Y/site-packages`
脚本	`prefix/bin`
数据	`prefix`
C 头文件	`prefix/include/pythonX.Yabiflags/distname`

不要求 --prefix 或 --exec-prefix 实际上指向备用 Python 安装；如果上面列出的目录尚不存在，则会在安装时创建它们。

顺便说一句，前缀方案很重要的真正原因很简单，标准的 Unix 安装使用前缀方案，但是 --prefix 和 --exec-prefix 由 Python 本身作为 sys.prefix 和 [ X205X]。因此，您可能认为您永远不会使用前缀方案，但是每次在没有任何其他选项的情况下运行 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"

将模块安装到当前驱动器上的 \Temp\Python 目录。

安装基础由--prefix选项定义； Windows 下不支持 --exec-prefix 选项，这意味着纯 Python 模块和扩展模块安装在同一位置。文件安装如下：

文件类型	安装目录
模块	`prefix\Lib\site-packages`
脚本	`prefix\Scripts`
数据	`prefix`
C 头文件	`prefix\Include{distname}`

自定义安装

有时，在替代安装部分中描述的替代安装方案并不能满足您的要求。您可能只想调整一两个目录，同时将所有内容保留在同一个基本目录下，或者您可能想要完全重新定义安装方案。无论哪种情况，您都在创建 自定义安装方案 。

要创建自定义安装方案，您可以从备用方案之一开始，并使用以下选项覆盖用于各种类型文件的一些安装目录：

文件类型	覆盖选项
Python 模块	`--install-purelib`
扩展模块	`--install-platlib`
所有模块	`--install-lib`
脚本	`--install-scripts`
数据	`--install-data`
C 头文件	`--install-headers`

这些覆盖选项可以是相对的、绝对的或根据安装基础目录之一明确定义的。（有两个安装基础目录，它们通常是相同的——它们仅在您使用 Unix“前缀方案”并提供不同的 --prefix 和 --exec-prefix 选项时有所不同；使用 [ X196X] 将覆盖为 --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 配置文件部分）：

[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 配置文件部分.

笔记

当一个虚拟环境被激活时，所有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。 site.py 在 Python 解释器执行时自动导入，除非提供 -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 配置文件

如上所述，您可以使用 Distutils 配置文件来记录任何 Distutils 选项的个人或站点首选项。也就是说，任何命令的任何选项都可以存储在两个或三个（取决于您的平台）配置文件之一中，在解析命令行之前将参考这些文件。这意味着配置文件将覆盖默认值，而命令行将依次覆盖配置文件。此外，如果应用多个配置文件，“较早”文件中的值将被“较晚”文件覆盖。

配置文件的位置和名称

配置文件的名称和位置因平台而异。在 Unix 和 Mac OS X 上，三个配置文件（按处理顺序）是：

文件类型	位置和文件名	提示
系统	`prefix/lib/pythonver/distutils/distutils.cfg`	(1)
个人的	`$HOME/.pydistutils.cfg`	(2)
本地	`setup.cfg`	(3)

在 Windows 上，配置文件是：

文件类型	位置和文件名	提示
系统	`prefix\Lib\distutils\distutils.cfg`	(4)
个人的	`%HOME%\pydistutils.cfg`	(5)
本地	`setup.cfg`	(3)

在所有平台上，可以通过传递 –no-user-cfg 选项来暂时禁用“个人”文件。

注意：

严格来说，系统范围的配置文件位于安装 Distutils 的目录中；在 Python 1.6 及更高版本的 Unix 下，如图所示。对于 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:\Python\Lib\distutils\distutils.cfg。在 Python 1.5.2 下，默认前缀是 C:\Program Files\Python，并且 Distutils 不是标准库的一部分——因此在标准 Python 1.5.2 安装中，系统配置文件将是 C:\Program Files\Python\distutils\distutils.cfg视窗。
在 Windows 上，如果 HOME 环境变量未定义，则 USERPROFILE 然后 HOMEDRIVE 和 [将尝试 X122X]HOMEPATH。这是由 Distutils 使用的 os.path.expanduser() 函数完成的。

配置文件的语法

Distutils 配置文件都具有相同的语法。配置文件分为几个部分。每个 Distutils 命令都有一个部分，另外还有一个 global 部分用于影响每个命令的全局选项。每个部分每行包含一个选项，指定为 option=value。

例如，下面是一个完整的配置文件，它只是强制所有命令默认安静运行：

[global]
verbose=0

如果它作为系统配置文件安装，它将影响当前系统上任何用户对任何 Python 模块分发的所有处理。如果它作为您的个人配置文件安装（在支持它们的系统上），它只会影响您处理的模块分发。如果它被用作特定模块分发的 setup.cfg，它只会影响该分发。

您可以覆盖默认的“build base”目录，并使 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 中被假定在目标 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++

本小节描述了在 Borland C++ 编译器 5.5 版中使用 Distutils 的必要步骤。首先，您必须知道 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 配置文件部分。）

也可以看看

C++Builder 编译器: Borland 免费 C++ 编译器的信息，包括下载页面的链接。
使用 Borland 的免费编译器创建 Python 扩展: 描述如何使用 Borland 的免费命令行 C++ 编译器构建 Python 的文档。

GNU C / Cygwin / MinGW

本节描述了在 Cygwin 和 MinGW 发行版中将 Distutils 与 GNU C/C++ 编译器一起使用的必要步骤。 2 对于用 Cygwin 构建的 Python 解释器，一切都应该可以工作，无需以下任何步骤。

并非所有扩展都可以使用 MinGW 或 Cygwin 构建，但很多都可以。最有可能不起作用的扩展是那些使用 C++ 或依赖于 Microsoft Visual C 扩展的扩展。

要让 Distutils 使用 Cygwin 编译您的扩展，您必须键入：

python setup.py build --compiler=cygwin

对于无 cygwin 模式 3 或 MinGW 类型的 Cygwin：

python setup.py build --compiler=mingw32

如果你想默认使用这些选项/编译器中的任何一个，你应该考虑将它写在你的个人或系统范围的 Distutils 配置文件中（参见 Distutils 配置文件部分。）

旧版本的 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，...），您可能也必须转换它们。转换后的文件必须与普通库位于相同的目录中。

也可以看看

使用 MinGW 在 MS Windows 平台上构建 Python 模块: 有关为 MinGW 环境构建所需库的信息。

脚注

1: 这也意味着您可以用同名的 OMF 库替换所有现有的 COFF 库。
2: 检查 https://www.sourceware.org/cygwin/ 和 http://www.mingw.org/ 了解更多信息
3: 那么您就没有可用的 POSIX 仿真，但您也不需要 cygwin1.dll。

安装 Python 模块（旧版） — Python 文档

安装 Python 模块（旧版）

简介

最佳案例：简单安装

新标准：Distutils

标准构建和安装

平台变化

拆分工作

建筑如何运作

安装工作原理

替代安装

替代安装：用户方案

替代安装：家庭方案

替代安装：Unix（前缀方案）

替代安装：Windows（前缀方案）

自定义安装

修改 Python 的搜索路径

Distutils 配置文件

配置文件的位置和名称

配置文件的语法

构建扩展：提示和技巧

调整编译器/链接器标志

在 Windows 上使用非 Microsoft 编译器

Borland/CodeGear C++

GNU C / Cygwin / MinGW

旧版本的 Python 和 MinGW