Python Packaging: sdist vs bdist

Why packages?

Let's start with a fundamental question: why package at all? Reason is fairly simple. Once you have created a package, then you are likely to use some of the code in other places. For example, you might want to do this:

What is a distribution?

A Python distribution is a versioned compressed archive file that contains your Python package. The distribution file is what an end-user (the client) will download from the internet when they run pip install.

There are two primary distribution types in use today: Built Distributions and Source Distributions.

Source Distribution (sdist)

A source distributions is the simpler of the two types of distributions. Intuitively speaking, an sdist is very similar to source code - the code that you write. Therefore, sdist will not include platform-specific binaries. The result is an archive (.tar.gz) that contains the source code of your package and instructions on how to build it, and the target system of your client will perform the actual build to create a bdist (wheel).

Creating an sdist is akin to sharing just the source. It doesn't build usable artifacts that the client can consume immediately. The advantage of this is that creating an sdist is the same for all platforms (Windows, Linux, Mac) and machines (32 Bit / 64 Bit). The disadvantage is that users have to build the package themselves once they download the sdist.

Built Distribution (bdist)

A built distribution, also sometimes referred to as a bdist, is more complex than an sdist in that it actually "builds" the package. Principally, bdist creates a distribution containing .so, .dll, .dylib for binary modules. The result is an archive that is specific to a platform (for example linux-x86_64) and to a version of Python (for example Python3.9).

Installing a bdist in the client is immediate, as they don't need to build anything (you as the package author have already built it for them, setuptools doesn't need to build it). The downside is that you as the package author have to build for multiple platforms and versions and upload all of the distributions for max compatibility.

Should I produce sdist or bdist for clients?

It is best practice to upload both, wheels and a source distribution, because any built distribution format only works for a subset of target systems. If there is not a platform-specific bidst that works for the end-user, they can go ahead and build locally w/ the sdist.