How to Deprecate a PyPI Package

Sometimes you have a package on PyPI that you want people to stop using.
There's no clear guidance from PyPI on how to do this, but there are a patterns
you can use to deal with new installs; this is a guide to them.

If you log in to PyPI, you can delete individual releases or an entire project.
This is a good option for a single botched release, but when removing a package
you make the name available for other users and leave no information for
existing users, which can cause confusion.

If you have a package you no longer maintain, but there's a fork or alternative
that users of your package should install, you can create a redirect package.
This is also useful if you want to change your package's name on PyPI, or if
there's a different name that's often used by mistake.
sklearn is a well-known example of this
approach.

The way this works is you create a minimal setup.py that requires the package
you want to redirect to without a version spec.

There's no standard way to show a warning message when installing a package via
PyPI. However, if a package fails to install error output is shown, so you can
fail on purpose to show a message that explains what the user should do
instead. skimage does this to direct users to install
scikit-image. Here's what that
setup.py looks like: