Distributing Python Modules

Email

distutils-sig@python.org

As a popular open source development project, Python has an activesupporting community of contributors and users that also make their softwareavailable for other Python developers to use under open source license terms.

This allows Python users to share and collaborate effectively, benefitingfrom the solutions others have already created to common (and sometimeseven rare!) problems, as well as potentially contributing their ownsolutions to the common pool.

This guide covers the distribution part of the process. For a guide toinstalling other Python projects, refer to theinstallation guide.

Note

For corporate and other institutional users, be aware that manyorganisations have their own policies around using and contributing toopen source software. Please take such policies into account when makinguse of the distribution and installation tools provided with Python.

Key terms

  • thePython Package Index is a publicrepository of open source licensed packages made available for use byother Python users

  • thePython Packaging Authority are the group ofdevelopers and documentation authors responsible for the maintenance andevolution of the standard packaging tools and the associated metadata andfile format standards. They maintain a variety of tools, documentationand issue trackers on bothGitHub andBitbucket.

  • distutils is the original build and distribution system first addedto the Python standard library in 1998. While direct use ofdistutilsis being phased out, it still laid the foundation for the current packagingand distribution infrastructure, and it not only remains part of thestandard library, but its name lives on in other ways (such as the nameof the mailing list used to coordinate Python packaging standardsdevelopment).

  • setuptools is a (largely) drop-in replacement fordistutils firstpublished in 2004. Its most notable addition over the unmodifieddistutils tools was the ability to declare dependencies on otherpackages. It is currently recommended as a more regularly updatedalternative todistutils that offers consistent support for morerecent packaging standards across a wide range of Python versions.

  • wheel (in this context) is a project that adds thebdist_wheelcommand todistutils/setuptools. This produces a cross platformbinary packaging format (called “wheels” or “wheel files” and defined inPEP 427) that allows Python libraries, even those including binaryextensions, to be installed on a system without needing to be builtlocally.

Open source licensing and collaboration

In most parts of the world, software is automatically covered by copyright.This means that other developers require explicit permission to copy, use,modify and redistribute the software.

Open source licensing is a way of explicitly granting such permission in arelatively consistent way, allowing developers to share and collaborateefficiently by making common solutions to various problems freely available.This leaves many developers free to spend more time focusing on the problemsthat are relatively unique to their specific situation.

The distribution tools provided with Python are designed to make itreasonably straightforward for developers to make their own contributionsback to that common pool of software if they choose to do so.

The same distribution tools can also be used to distribute software withinan organisation, regardless of whether that software is published as opensource software or not.

Installing the tools

The standard library does not include build tools that support modernPython packaging standards, as the core development team has found that itis important to have standard tools that work consistently, even on olderversions of Python.

The currently recommended build and distribution tools can be installedby invoking thepip module at the command line:

python-mpipinstallsetuptoolswheeltwine

Note

For POSIX users (including macOS and Linux users), these instructionsassume the use of avirtual environment.

For Windows users, these instructions assume that the option toadjust the system PATH environment variable was selected when installingPython.

The Python Packaging User Guide includes more details on thecurrentlyrecommended tools.

Reading the Python Packaging User Guide

The Python Packaging User Guide covers the various key steps and elementsinvolved in creating and publishing a project:

How do I…?

These are quick answers or links for some common tasks.

… choose a name for my project?

This isn’t an easy topic, but here are a few tips:

  • check the Python Package Index to see if the name is already in use

  • check popular hosting sites like GitHub, Bitbucket, etc to see if thereis already a project with that name

  • check what comes up in a web search for the name you’re considering

  • avoid particularly common words, especially ones with multiple meanings,as they can make it difficult for users to find your software whensearching for it

… create and distribute binary extensions?

This is actually quite a complex topic, with a variety of alternativesavailable depending on exactly what you’re aiming to achieve. See thePython Packaging User Guide for more information and recommendations.