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.

Add Deprecation Warnings

If there's code in your module that shouldn't be used, but you aren't ready to disable completely, you can use deprecation warnings like this:

import warnings

warnings.warn("deprecated", DeprecationWarning)

There's not much detail but it is covered in the official Python docs.

Just Delete It

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.

Provide a Redirect

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.

from setuptools import setup
setup(name = "deprecated-package",
      version="1.0.0",
      install_requires=["maintained-package"],
)

Now when people install deprecated-package pip will automatically install the latest version of maintained-package instead.

If the name you're using has no releases 0.0.0 is a fine version number, but otherwise you can bump the major version by one to catch new installs while leaving old releases unchanged.

Intentionally Fail During Install

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:

import sys

# XXX This if statement lets you actually build the package
if not 'sdist' in sys.argv:
    sys.exit('\n*** Please install the `scikit-image` package '
            '(instead of `skimage`) ***\n')

# normal setup(...) follows

This is effective when a package stops working completely or the upgrade path isn't straightforward.

---

And that's it. If you know a better way to deprecate a package or found this useful I'd love to hear about it. Ψ