Packaging Python modules

The Python Packaging User Guide has excellent guidance on packaging Python projects - in particular, use the information on packaging and distributing projects, and the suggested tools. Python projects that provide a package should include and setup.cfg configuration files:

from setuptools import setup


    description='A short description of the package',

    author='Sam Clements',
    license='MIT License',


        'Development Status :: 3 - Alpha',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 2',
        'Programming Language :: Python :: 2.6',
        'Programming Language :: Python :: 2.7',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.3',
        'Programming Language :: Python :: 3.4'

Notes on specific metadata items:

Packages that run on Python 2 and 3 should ensure they have a setup.cfg file that configures bdist_wheel to mark the wheel as ‘universal’ (otherwise, the wheel will declare that it is only for the version of Python it was built on).



A new python package can be registered to PyPI with:

python register

Python packages can generally be released with:

python sdist bdist_wheel upload

Tox can be used to automate package releases, by including a test environment that runs the release commands:

commands=python sdist bdist_wheel upload

In the unusual case that a package supplies metadata depending on which Python version it is running on (see complex_setup_example), you’ll need to run bdist_wheel for each of those Python versions. While source distributions run when installing a package, built distributions run when creating the package).

    python2 sdist upload
    python2 bdist_wheel upload
    python3 bdist_wheel upload


README files for Python projects should use Markdown (see this commit). The README should include links to the GitHub repository, any packages on PyPi,builds on Travis-CI and documentation on Read The Docs (which is especially useful when the README is shown in multiple places).

# EXAMPLE [![](]( [![](]( [![](]( [![](](

A short description of the project.

* [Source on GitHub](
* [Packages on PyPI](
* [Documentation on Read the Docs](
* [Builds on Travis CI](


Run `EXAMPLE --help` for a list of availible subcommands.


pip install EXAMPLE


**EXAMPLE** is licenced under the [MIT Licence](


Written by [Sam Clements](

You will need to create a file so that the README is included in the package:


README files for older Python projects using reStructuredText can use the rst-lint tool for checking the validity of a README file.


.. image::
    :alt: example on PyPI

.. image::
    :alt: example on PyPI

.. image::
    :alt: Documentation for example on Read The Docs

.. image::
    :alt: Travis-CI build status for example

.. image::
    :alt: GitHub issues for example


Short description of the project.

* `Source on GitHub <>`_
* `Documentation on Read the Docs <>`_
* `Packages on PyPI <>`_
* `Builds on Travis CI <>`_