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?

`python setup.py` runs the file. `python -m build` uses the `build` module (which may in-turn read a setup.py file, if it exists) — OneCricketeer, Jul 28 '21 at 01:18
@OneCricketeer The [doc](https://pypa-build.readthedocs.io/en/stable/differences.html#setup-py-sdist-bdist-wheel) 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`? — oeter, Jul 28 '21 at 02:07

score 12 · Accepted Answer · answered Sep 05 '22 at 10:07

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.

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

1 Answers1