setup.py 已被弃用吗？

Is setup.py deprecated?

不，setup.py 和 Setuptools 并没有被废弃。

Setuptools 作为 Python 项目的 build backend，完全可以正常使用。 而 setup.py 是一个有效的配置文件，适用于 Setuptools，它是用 Python 编写的，而不是例如 TOML 格式（其他工具，如 nox 及其 noxfile.py 配置文件，或 pytest 和 conftest.py 也采用了类似的做法）。

然而，python setup.py 和将 setup.py 用作命令行工具的做法已经被废弃。

这意味着以下命令 不得 再运行 :

  • python setup.py install

  • python setup.py develop

  • python setup.py sdist

  • python setup.py bdist_wheel

No, setup.py and Setuptools are not deprecated.

Setuptools is perfectly usable as a build backend for packaging Python projects. And setup.py is a valid configuration file for Setuptools that happens to be written in Python, instead of in TOML for example (a similar practice is used by other tools like nox and its noxfile.py configuration file, or pytest and conftest.py).

However, python setup.py and the use of setup.py as a command line tool are deprecated.

This means that commands such as the following MUST NOT be run anymore:

  • python setup.py install

  • python setup.py develop

  • python setup.py sdist

  • python setup.py bdist_wheel

应该使用什么命令？

What commands should be used instead?

已废弃

推荐

python setup.py install

python -m pip install .

python setup.py develop

python -m pip install --editable .

python setup.py sdist

python -m build [1]

python setup.py bdist_wheel

为了安装基于 setuptools 的项目，过去常用运行 setup.py 的 install 命令，例如 : python setup.py install。 如今，推荐的方法是直接使用 pip，命令如下 : python -m pip install .。 其中的点 . 实际上是一个文件系统路径，表示当前目录。 实际上，pip 接受一个指向项目源代码树目录的本地文件系统路径作为 install 子命令的参数。 因此，以下命令也是有效的 : python -m pip install path/to/project。

至于 develop 模式（即可编辑模式）的安装， 不再使用 python setup.py develop， 而是可以使用 pip 的 install 子命令中的 --editable 选项 : python -m pip install --editable .。

构建 源代码分发包 和 wheel 的一种推荐、简单且直接的方法是使用 build 工具，命令如下 : python -m build， 该命令会触发生成这两种分发格式。 如有需要，可以使用 --sdist 和 --wheel 选项来仅生成其中一个。 请注意，build 工具需要单独安装。

命令 python setup.py install 在 setuptools 版本 58.3.0 中已被废弃。

Deprecated

Recommendation

python setup.py install

python -m pip install .

python setup.py develop

python -m pip install --editable .

python setup.py sdist

python -m build [2]

python setup.py bdist_wheel

In order to install a setuptools based project, it was common to run setup.py's install command such as: python setup.py install. Nowadays, the recommended method is to use pip directly with a command like this one: python -m pip install .. Where the dot . is actually a file system path, it is the path notation for the current directory. Indeed, pip accepts a path to a project's source tree directory on the local filesystem as argument to its install sub-command. So this would also be a valid command: python -m pip install path/to/project.

As for the installation in develop mode aka editable mode, instead of python setup.py develop one can use the --editable option of pip's install sub-command: python -m pip install --editable ..

One recommended, simple, and straightforward method of building source distributions and wheels is to use the build tool with a command like python -m build which triggers the generation of both distribution formats. If necessary the --sdist and --wheel options can be used to generate only one or the other. Note that the build tool needs to be installed separately.

The command python setup.py install was deprecated in setuptools version 58.3.0.

其他命令呢？

What about other commands?

其他 python setup.py 命令有哪些替代品？

What are some replacements for the other python setup.py commands?

python setup.py test

建议使用测试运行器，例如 pytest 。

The recommendation is to use a test runner such as pytest.

python setup.py check, python setup.py register, 和 python setup.py upload

一个值得信赖的替代工具是 twine :

  • python -m twine check --strict dist/*

  • python -m twine register dist/*.whl [3]

  • python -m twine upload dist/*

A trusted replacement is twine:

  • python -m twine check --strict dist/*

  • python -m twine register dist/*.whl [4]

  • python -m twine upload dist/*

python setup.py --version

一种可能的替代解决方案（除其他外）是依赖 setuptools-scm :

  • python -m setuptools_scm

A possible replacement solution (among others) is to rely on setuptools-scm:

  • python -m setuptools_scm

剩余命令

Remaining commands

本指南不对这些命令提出替代解决方案的建议：

This guide does not make suggestions of replacement solutions for those commands:

  • alias

  • bdist

  • bdist_dumb

  • bdist_egg

  • bdist_rpm

  • build

  • build_clib

  • build_ext

  • build_py

  • build_scripts

  • clean

  • dist_info

  • easy_install

  • editable_wheel

  • egg_info

  • install_data

  • install_egg_info

  • install_headers

  • install_lib

  • install_scripts

  • rotate

  • saveopts

  • setopt

  • upload_docs

自定义命令呢？

What about custom commands?

同样，自定义的 setup.py 命令也已弃用。 建议将这些自定义命令迁移到任务运行工具或其他类似工具。 一些此类工具的例子包括: chuy、make、nox 或 tox、pydoit、pyinvoke、taskipy 和 thx。

Likewise, custom setup.py commands are deprecated. The recommendation is to migrate those custom commands to a task runner tool or any other similar tool. Some examples of such tools are: chuy, make, nox or tox, pydoit, pyinvoke, taskipy, and thx.

自定义构建步骤呢？

What about custom build steps?

自定义构建步骤，例如覆盖现有步骤（如 build_py、 build_ext 和 bdist_wheel）或添加新的构建步骤，并未被弃用。这些步骤将会按预期自动调用。

Custom build steps that for example either overwrite existing steps such as build_py, build_ext, and bdist_wheel or add new build steps are not deprecated. Those will be automatically called as expected.

是否应删除 setup.py？

Should ``setup.py`` be deleted?

尽管将 setup.py 用作可执行脚本的方式已被弃用，但作为 setuptools 的配置文件仍然是完全可行的。通常不需要修改 setup.py 文件。

Although the usage of setup.py as an executable script is deprecated, its usage as a configuration file for setuptools is absolutely fine. There is likely no modification needed in setup.py.

pyproject.toml 是必需的吗？

Is ``pyproject.toml`` mandatory?

虽然目前从技术上讲还不是必需的，但 强烈推荐 项目在源代码树的根目录下拥有一个 pyproject.toml 文件，其内容应如下所示：

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

关于此内容的更多细节，请参阅指南 如何使基于 setup.py 的项目现代化？。

在没有 pyproject.toml 文件及其 [build-system] 表的情况下，构建前端的标准回退行为是假设构建后端为 setuptools。

While it is not technically necessary yet, it is STRONGLY RECOMMENDED for a project to have a pyproject.toml file at the root of its source tree with a content like this:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

The guide 如何使基于 setup.py 的项目现代化？ has more details about this.

The standard fallback behavior for a build frontend in the absence of a pyproject.toml file and its [build-system] table is to assume that the build backend is setuptools.

为什么？这一切意味着什么？

Why? What does it all mean?

一种看法是，setuptools 的范围现在已经缩小到构建后端的角色。

One way to look at it is that the scope of setuptools has now been reduced to the role of a build backend.

在哪里可以阅读更多相关信息？

Where to read more about this?