Tool recommendations

If you’re familiar with Python packaging and installation, and just want to know what tools are currently recommended, then here it is.

Installation Tool Recommendations

  • Use pip to install Python packages from PyPI. [1] [2] Depending on how pip is installed, you may need to also install wheel to get the benefit of wheel caching. [3]
  • Use virtualenv, or venv to isolate application specific dependencies from a shared Python installation. [4]
  • If you’re looking for management of fully integrated cross-platform software stacks, consider:
    • buildout: primarily focused on the web development community
    • Spack, Hashdist, or conda: primarily focused on the scientific community.

Packaging Tool Recommendations

Publishing Platform Migration

The original Python Package Index implementation (hosted at pypi.python.org) is being phased out in favour of an updated implementation hosted at pypi.org. Both interfaces share a common database backend and file store, allowing the latter to assume more default responsibilities as it becomes more capable.

Users consistently using the latest versions of the recommended tools above with their default settings don’t need to worry about this migration, but users running older versions, or not using the default settings, will need to update their configurations in line with the recommendations below.

Publishing releases

pypi.org became the default upload platform in September 2016.

Uploads through pypi.python.org will be switched off on July 3, 2017.

The default upload settings switched to pypi.org in the following versions:

  • twine 1.8.0
  • setuptools 27.0.0
  • Python 2.7.13 (distutils update)
  • Python 3.4.6 (distutils update)
  • Python 3.5.3 (distutils update)
  • Python 3.6.0 (distutils update)

Browsing packages

pypi.python.org is currently still the default interface for browsing packages (used in links from other PyPA documentation, etc).

pypi.org is fully functional for purposes of browsing available packages, and some users may choose to opt in to using it.

pypi.org is expected to become the default recommended interface for browsing once the limitations in the next two sections are addressed (at which point attempts to access pypi.python.org will automatically be redirected to pypi.org).

Downloading packages

pypi.python.org is currently still the default host for downloading packages.

pypi.org is fully functional for purposes of downloading packages, and some users may choose to opt in to using it, but its current hosting setup isn’t capable of handling the full bandwidth requirements of being the default download source (even after accounting for the Fastly CDN).

pypi.org is expected to become the default host for downloading packages once it has been redeployed into an environment capable of handling the associated network load.

Managing published packages and releases

pypi.python.org provides an interface for logged in users to manage their published packages and releases.

pypi.org does not currently provide such an interface.

The missing capabilities are being tracked as part of the Shut Down Legacy PyPI milestone.


[1]There are some cases where you might choose to use easy_install (from setuptools), e.g. if you need to install from Eggs (which pip doesn’t support). For a detailed breakdown, see pip vs easy_install.
[2]The acceptance of PEP 453 means that pip will be available by default in most installations of Python 3.4 or later. See the rationale section from PEP 453 as for why pip was chosen.
[3]get-pip.py and virtualenv install wheel, whereas ensurepip and venv do not currently. Also, the common “python-pip” package that’s found in various linux distros, does not depend on “python-wheel” currently.
[4]Beginning with Python 3.4, venv will create virtualenv environments with pip installed, thereby making it an equal alternative to virtualenv. However, using virtualenv will still be recommended for users that need cross-version consistency.
[5]

Although you can use pure distutils for many projects, it does not support defining dependencies on other projects and is missing several convenience utilities for automatically populating distribution metadata correctly that are provided by setuptools. Being outside the standard library, setuptools also offers a more consistent feature set across different versions of Python, and (unlike distutils), setuptools will be updated to produce the upcoming “Metadata 2.0” standard formats on all supported versions.

Even for projects that do choose to use distutils, when pip installs such projects directly from source (rather than installing from a prebuilt wheel file), it will actually build your project using setuptools instead.

[6]distribute (a fork of setuptools) was merged back into setuptools in June 2013, thereby making setuptools the default choice for packaging.
[7]PyPI currently only allows uploading Windows and Mac OS X wheels, and they should be compatible with the binary installers provided for download from python.org. Enhancements will have to be made to the wheel compatibility tagging scheme before linux wheels will be allowed.