Shouldpyproject.toml be added?¶

Apyproject.toml file is strongly recommended.The presence of apyproject.toml file itself does not bring much.[1]What is actually strongly recommended is the[build-system] table inpyproject.toml.

Note that it has influence on the build isolation feature of pip,see below.

Shouldsetup.py be deleted?¶

No,setup.py can exist in a modernSetuptools based project.Thesetup.py file is a valid configuration file for setuptoolsthat happens to be written in Python.However, the following commands are deprecated andMUST NOT be run anymore,and their recommended replacement commands should be used instead:

For more details:

• Is setup.py deprecated?

Where to start?¶

Theproject must contain apyproject.toml file at the root of its source treethat contains a[build-system] table like so:

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

This is the standardized method of lettingbuild frontends knowthatSetuptools is thebuild backend for this project.

Note that the presence of apyproject.toml file (even if empty)triggerspip to change its default behavior to usebuild isolation.

For more details:

• Packaging and distributing projects

• Declaring build system dependencies: the [build-system] table

• Build System Interface

How to handle additional build-time dependencies?¶

On top of setuptools itself,ifsetup.py depends on other third-party libraries (outside of Python’s standard library),those must be listed in therequires list of the[build-system] table,so that the build frontend knows to install themwhen building thedistributions.

For example, asetup.py file such as this:

importsetuptoolsimportsome_build_toolkit# comes from the `some-build-toolkit` librarydefget_version():version=some_build_toolkit.compute_version()returnversionsetuptools.setup(name="my-project",version=get_version(),)

requires apyproject.toml file like this (setup.py stays unchanged):

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

For more details:

• Declaring build system dependencies: the [build-system] table

What is the build isolation feature?¶

Build frontends typically create an ephemeral virtual environmentwhere they install only the build dependencies (and their dependencies)that are listed underbuild-system.requiresand trigger the build in that environment.

For some projects this isolation is unwanted and it can be deactivated as follows:

• python-mbuild--no-isolation

• python-mpipinstall--no-build-isolation

For more details:

• Build System Interface

How to handle packaging metadata?¶

All static metadata can optionally be moved to a[project] table inpyproject.toml.

For example, asetup.py file such as this:

importsetuptoolssetuptools.setup(name="my-project",version="1.2.3",)

can be entirely replaced by apyproject.toml file like this:

[build-system]requires=["setuptools"]build-backend="setuptools.build_meta"[project]name="my-project"version="1.2.3"

ReadDeclaring project metadata: the [project] table for the full specificationof the content allowed in the[project] table.

How to handle dynamic metadata?¶

If some packaging metadata fields are not staticthey need to be listed asdynamic in this[project] table.

For example, asetup.py file such as this:

importsetuptoolsimportsome_build_toolkitdefget_version():version=some_build_toolkit.compute_version()returnversionsetuptools.setup(name="my-project",version=get_version(),)

can be modernized as follows:

[build-system]requires=["setuptools","some-build-toolkit",]build-backend="setuptools.build_meta"[project]name="my-project"dynamic=["version"]

importsetuptoolsimportsome_build_toolkitdefget_version():version=some_build_toolkit.compute_version()returnversionsetuptools.setup(version=get_version(),)

For more details:

• dynamic

What if something that can not be changed expects asetup.py file?¶

For example, a process exists that can not be changed easilyand it needs to execute a command such aspythonsetup.py--name.

It is perfectly fine to leave asetup.py file in the project source treeeven after all its content has been moved topyproject.toml.This file can be as minimalistic as this:

importsetuptoolssetuptools.setup()

Where to read more about this?¶

• pyproject.toml specification

• Build System Interface

• Build System Support