Python commands to build distribution setup.py build vs python -m build

Question

I'm learning about Python packaging, and according to this guide, the command to build a python distribution package seems to be python3 -m build.

But I aslo found that there is a command line interface for setup.py file from setuptools:

$ python setup.py --help-commands
Standard commands:
  build             build everything needed to install
  sdist             create a source distribution (tarball, zip file, etc.)
  bdist             create a built (binary) distribution
  bdist_dumb        create a "dumb" built distribution
  bdist_rpm         create an RPM distribution
  ...

It seems that python setup.py build, sdist or bdist can aslo build distribution, but I didn't find detailed intructions for these commands, the setuptools command reference lacks explanation for build sdist bdist.

So I'm a bit confused, what is the difference between python setup.py build and python -m build, or between python setup.py sdist and python -m build --sdist? Is the python setup.py command deprecated hence the lack of full documentation? When should I use python -m build or python setup.py build?

Any help would be appreciated.

---

Update: The doc of build module says “build is roughly the equivalent of setup.py sdist bdist_wheel but with PEP 517 support, allowing use with projects that don’t use setuptools”.

So should I always prefer build module rather than running python setup.py manually?. Is there still a use-case for setup.py build?

Answer 1

Citing Why you shouldn't invoke setup.py directly by Paul Ganssle.

• The setuptools project has stopped maintaining all direct invocations of setup.py years ago, and distutils is deprecated.
• There are undoubtedly many ways that your setup.py-based system is broken today, even if it's not failing loudly or obviously.
• Direct invocations of setup.py cannot bootstrap their own dependencies, and so some CLI is necessary for dependency management.
• The setuptools project no longer wants to provide any public CLI, and will be actively removing the existing interface (though the time scale for this is long).
• PEP 517, 518 and other standards-based packaging are the future of the Python ecosystem and a lot of progress has been made on making this upgrade seamless.

Here's a summary table of the setup.py way and the newer recommended method:

setup.py	New command
setup.py sdist	python -m build (with build)
setup.py bdist_wheel	python -m build (with build)
setup.py test	pytest (usually via tox or nox)
setup.py install	pip install
setup.py develop	pip install -e
setup.py upload	twine upload (with twine)
setup.py check	twine check (this doesn't do all the same checks but it's a start)
Custom commands	tox and nox environments.