Fix broken wheels that you have already uploaded to PyPI by making a fixed wheel, and adding a build tag to the filename of the fixed wheel.

If you upload files to PyPI, and then you find that the files are broken in some way, you will probably want to replace the broken files with better ones. You will soon find that PyPI will not let you do that, complaining that there is already a file with the given filename.

One reason that might be the case, is because PyPI runs on a Content Delivery Network (CDN).

When you upload your files to pypi, it spreads copies of these files out to the CDN. Imagine you could upload a file with the same filename to pypi. Because the content is spread out across the CDN, it would take time for the new contents to replace the old, meaning that, at least for a while, there would be two different versions of the same file available on the CDN, depending on time and on which part of the CDN you happened to be downloading from.

The upshot is - if you make a release, and upload files for that release, and then find that you made a mistake, you cannot upload new files with the same filenames.

Your options at that point are:

• delete the release with bad files and make a new release with a different version number (and therefore different file names);
• upload new versions of the release files with a build tag number in the filename.

Build tags are a little-known feature of wheel filenames that allow you to change the filenames of PyPI wheel files, without changing the version number.

For example, here is a wheel filename with no build tag:

h5py-2.6.0-cp27-cp27m-manylinux1_i686.whl

This filename splits at the dashes (-) into five tags:

• package name : h5py;
• package version : 2.6.0;
• Python version : cp27 (CPython version 2.7);
• Python ABI : cp27m;
• platform : manylinux1_i686.

The build tag is an optional extra tag, starting with a digit, that comes after the package version tag and before the Python version tag. For example, here is the same wheel filename as above, with build tag 1:

h5py-2.6.0-1-cp27-cp27m-manylinux1_i686.whl

When a user asks pip to install h5py, it will find the wheel with the highest (on lexical sort) value of the build tag. Thus pypi will find h5py-2.6.0-1-cp27-cp27m-manylinux1_i686.whl before h5py-2.6.0-cp27-cp27m-manylinux1_i686.whl and h5py-2.6.0-2-cp27-cp27m-manylinux1_i686.whl before h5py-2.6.0-1-cp27-cp27m-manylinux1_i686.whl.

If you need to fix the files for a release, you can make new versions of the files with a new (or higher) build tag, and upload those to pypi. In due course pip will find the files with the highest build tag.

For safety, I (MB) recommend removing the old broken files from pypi, after you have uploaded the fixed files with a build tag.

Although it is somewhere between good to essential to automate wheel builds, I have not tried to automate adding build tags to the wheel filenames. I have rarely had to use build tags, but when I did, I built the wheels in the usual way, with the usual filenames, downloaded the wheels to my local machine, added the build tags with the script below, and then uploaded the files to PyPI.

See: add_build.py for a script to add build tags to wheel filenames.