Why you shouldn't invoke setup.py directly

TL;DR: The setuptools team no longer wants to be in the business of providing a command line interface and is actively working to become just a library for building packages.

This does not mean that setuptools itself is deprecated, or that using setup.py to configure your package builds is going to be removed. The only thing you must stop doing is directly executing the setup.py file — instead delegate that to purpose-built or standards-based tools, preferably those that work with any build backend.

For a long time, setuptools and distutils were the only game in town when it came to creating Python packages, and both of these provided a simple enough interface: you write a setup.py file that invokes the setup() method, you get a Makefile-like interface exposed by invoking python setup.py <command>. So, for example, to build a source distribution, you would run python setup.py sdist, or to run your tests you would run python setup.py test, or to install the package you would run python setup.py install. You may still find advice all over the place that involves invoking setup.py directly, but unfortunately this is no longer good advice because as of the last few years all direct invocations of setup.py are effectively deprecated in favor of invocations via purpose-built and/or standards-based CLI tools like pip, build and tox. In this article, I will explain why this has come to be, and hopefully make the case that this isn't even a bad thing.

I realize that this article is quite long, and unfortunately this is the short version. Much nuance and history is lost here, even though the post is already long enough that it is destined for the limbo of a bookmarks folder called "to read later". Despite the fact that no one will read more than the next 3 paragraphs, I hope that this article can be useful when you want to advocate against the use of setup.py: when you make a PR or a comment in a slack channel, you can link to this Proustian monstrosity and hope that your audience pales before the prospect of reading through the whole thing and just assents to whatever you're asking them to do.

Leave a Comment