Python Packaging Guide

Release

PyPA

November 10, 2013

Contents

i
ii
 Python Packaging Guide, Release

Page Status Incomplete 1

Last Reviewed 2013-10-29

1 The main index page will only be marked “Complete”, when all pages are marked “Complete”, which they are not.

Contents 1
Python Packaging Guide, Release

2 Contents
 CHAPTER 1

Introduction

Page Status Complete

Last Reviewed 2013-11-02

1.1 What’s covered

• Quick Recommendations for what tools you should be using now.

• Instructions for installing setuptools, pip, and virtualenv.
• An Installation Guide for setting up environments and installing distributions.
• A Packaging Guide for creating and releasing distributions.
• Summaries of the most relevant projects.
• Summaries of the most relevant PEPs.
• The Future of Python Packaging.
• A Packaging Timeline.
• Additional Resources we deem helpful.
• A Glossary of packaging and installation terms.

1.2 Where to get support

• For support related to a specific project, see the mailing list links on the Projects page.
• For something more general, or when you just not sure, use the distutils-sig list.

1.3 How to help

• Get involved with one of mainstream packaging projects.

3
Python Packaging Guide, Release

• Help us catalog and discuss the current problems in packaging and installation. See the The issue tracker for the
problems in packaging maintained by PyPA.
• Discuss PEPs and long terms plans at distutils-sig.
• Help make this guide better. Log issues or make pull requests at https://bitbucket.org/pypa/python-packaging-
user-guide

1.4 About the Guide

The Guide is maintained by the PyPA and aims to be the authoritative resource on how to release and install distribu-
tions in python.
The guide was originally forked from the “Hitchhikers Guide to Packaging” in March 2013.

1.5 About ‘Page Status’

Each page, even this one, will state at the top whether it’s “Complete” or “Incomplete”. Admittedly, a binary distinction
is not very precise, but most pages will additionally offer a footnote to better explain what’s not complete or wrong.
Also, each page will give a “Last Reviewed” date, wich will only be updated by a PyPA member when a meaningful
review is done to determine the status.
Why do this? See here.

4 Chapter 1. Introduction
 CHAPTER 2

Quick Recommendations

Page Status Complete

Last Reviewed 2013-11-03
If you’re familiar with Python packaging and installation, and just want to know what toolset is currently recom-
mended, then here it is.
If you’re less familiar with Python packaging or installation, and would like more details, then proceed to the Packaging
Guide and Installation Guide.
If you’re interested in learning more about current areas of development, see The Future of Python Packaging.

2.1 Installation Tool Recommendations

• Use pip to install Python packages from PyPI. 1 2

3
• Use virtualenv to isolate application specific dependencies from a shared Python installation.
• Use pip wheel to create a cache of wheel distributions, for the purpose of speeding up subsequent installations.
4

• If you’re looking for management of fully integrated cross-platform software stacks, consider buildout (primar-
ily focused on the web development community) or Hashdist, or conda (both primarily focused on the scientific
community).

2.2 Packaging Tool Recommendations

• Use setuptools to package and publish Python packages to PyPI. 5 6

1 If you need to install from the Egg format (which pip doesn’t support), you can use easy_install (from setuptools) or buildout. Eggs are
intended to be replaced by Wheels, so they should become less common over time.
2 The acceptance of PEP453 means that pip will likely be available by default in most installations of Python 3.4 or later.
3 The acceptance of PEP453 means that users of Python 3.4 or later will likely be able to use the standard library’s own pyvenv tool instead of

virtualenv. However, using virtualenv will still be recommended for users that need cross-version consistency.
4 For more information, see the pip guide to Building and Installing Wheels.
5 distribute (a fork of setuptools) was merged back into setuptools in June 2013, thereby making setuptools the default choice for packaging.
6 When building from source (rather than installing from a wheel file), pip ensures that packages that use the standard library’s distutils

module are built with setuptools instead.

5
Python Packaging Guide, Release

• If your project includes binary extensions, use the bdist_wheel setuptools extension available from the wheel
project, to create and publish wheel distributions for Windows and Mac OS X for your project on PyPI. These
wheel files should be compatible with the binary installers provided for download from python.org. 7

7 pip and the wheel format don’t currently offer good tools for handling arbitrary external binary dependencies. Accordingly, PyPI currently only

allows platform specific wheel distributions to be uploaded for Windows and Mac OS X. External binary dependencies are currently best handled by
building custom wheel files with the correct dependencies, by using one of the fully integrated cross-platform software stack management systems
mentioned in the installation tools section, or by using platform specific tools.

6 Chapter 2. Quick Recommendations

 CHAPTER 3

Installing the Tools

Page Status Complete

Last Reviewed 2013-10-29
Instructions for installing or upgrading setuptools, pip, and virtualenv, the de facto tools for Python packaging and
installation.
On Linux and OSX, these tools will usually be available for the system python from a system package manager (e.g.
yum or apt-get for linux, or homebrew for OSX). Unfortunately, there is often delay in getting the latest version this
way, so in most cases, you’ll want to use the instructions below.

3.1 setuptools

setuptools supports building, packaging, and uploading projects to PyPI, and is also a requirement of pip.
To install setuptools from scratch:
1
1. Securely download ez_setup.py.
2. Then run the following (which may require administrator access):
$ python ez_setup.py

Warning: Prior to Setuptools-1.0, ez_setup.py was not secure, and is currently only secure when your
environment contains secure versions of either curl, wget, or powershell. 2 If you’re not sure if you’re
environment fulfills this requirement, then the safest approach is to securely download the setuptools archive
directly from PyPI, unpack it, and run “python setup.py install” from inside the unpacked directory.

To upgrade a previous install of setuptools or distribute, there are two scenarios.

1. You currently have some version of pip.
$ pip install --upgrade setuptools

Note: If you have distribute, this will upgrade to you distribute-0.7.X, which is just a wrapper, that depends on
setuptools. The end result will be that you have distribute-0.7.X (which does nothing) and the latest setuptools
1 “Secure” in this context means using a modern browser or a tool like curl that verifies SSL certificates when downloading from https URLs.

7
Python Packaging Guide, Release

installed. If you’d prefer not to end up with the distribute wrapper, then instead, run $ pip uninstall
distribute, then go back to step #1 above which installs setuptools from scratch.

2. You currently don’t have pip.

Follow the pip install procedure below, then come back and run:
$ pip install --upgrade setuptools

3.2 pip
2
pip requires setuptools, which has to be installed first (see section above), before pip can run.
2
Securely download get-pip.py.
Then run the following (which may require administrator access), to install (or upgrade to) the latest version of pip:
$ python get-pip.py

3.3 virtualenv

Although it’s not strictly required for the tutorials in this guide, using virtualenv to create isolated Python environments
(that already contain copies of setuptools and pip) is a common practice when installing packages.
For more details, see http://www.virtualenv.org.
To install virtualenv, pip should already be installed (see section above).
To install or upgrade, run the following (which may require administrator access):
$ pip install --upgrade virtualenv

2 As of pip 1.4, pip started requiring setuptools, not distribute (a fork of setuptools). setuptools and distribute are now merged back together as

“setuptools”.

8 Chapter 3. Installing the Tools

 CHAPTER 4

Installation Guide

Page Status Incomplete

Last Reviewed 2013-11-03
A guide to installing python distributions.

4.1 What is “installation”?

FIXME

What to cover:

1. distutils/sysconfig schemes
2. global vs user installs
3. virtual environments

4.2 Introduction to PyPI

FIXME

4.3 What tools to use

virtualenv and pip

FIXME

What to cover:

1) Why virtualenv (what about pyenv? buildout?)

2) Why pip (compare pip vs easy_install in detail); use rationale from PEP453
3) When to use easy_install ([multi-version] eggs)

9
Python Packaging Guide, Release

4.4 Getting started with virtualenv

FIXME

4.5 Getting started with pip

FIXME

What to cover:

1. link to:
- pip’s quickstart (which needs improvement)
- pip’s feature overview (which doesn’t exist atm)
- pip’s cookbook
- pip’s guide on "wheel caching"
- pip’s usage (which needs better subcommand descriptions and more examples)

4.6 Advanced Topics

FIXME

What to cover:

1. When to use yum/apt OS packages

2. debian/unbuntu considerations (dist-packages and it’s /usr and /usr/local schemes)
4. centos/redhat considerations (just one global scheme, unlike debian)
5. the world of OSX (homebrew, macports etc...)
6. windows installation considerations
7. "deploying" python software in the real world
8. easy_install’s pth sys.path modification (that can override --user installs)

10 Chapter 4. Installation Guide

 CHAPTER 5

Packaging Guide

Page Status Incomplete

Last Reviewed 2013-11-03
A guide to packaging python projects and uploading them to PyPI.

5.1 What is “packaging”?

FIXME

What to cover:

1. the uses of the term "packaging"

a. creating/maintaining a setup.py
b. the act of creating distributions (or packages)
2. creating binary packages, involves "building" or compiling.
3. Why package at all? what’s the point? Is it just about PyPI?

5.2 Current packaging formats

FIXME

What to cover:

1) sdist and wheel are the most relevant currently

2) what defines an sdist? (sdist 2.0 is coming)
3) wheel? why not egg? what was wrong with egg?

5.3 What tools to use

setuptools and wheel (for bdist_wheel)

11
Python Packaging Guide, Release

FIXME

What to cover:

1. Why setuptools (and not distutils)?

2. What happened to distutils2? Can we be trusted again to give recommendations? : )
3. Is setuptools stable and supported by PyPA?
4. Why the wheel project implementation of wheel? It’s not a PyPA project?
5. twine for uploading?

5.4 Getting started with setuptools

FIXME

What to cover:

1. link to the setuptools "Getting Started" guide

(which doesn’t really exist atm, but needs to)
2. Highlight which features are relevant *today*
(ideally a link into setuptools)
3. Explain how setuptools builds on top of distutils (maybe cover some hisory of why it’s like this)
(ideally a link into setuptools docs)
4. link to the "Complete Guide to setup.py", which covers all subcommands and keywords (including dis
(this does *not* exist atm, but ideally it exists in the setuptools docs, not in these docs)

5.5 Getting started with wheel

FIXME

What to cover:

1. installing the wheel project

2. using bdist_wheel (and why "pip wheel" is for a different use case and covered in the install guid
3. the pep425 tagging system
4. "universal" wheels
5. the current PyPI upload block on linux platform wheels (and why they’re blocked)

5.6 Advanced Topics

FIXME

What to cover:

1. Building Rpms and Debs for packages (also for whole environments)
2. private non-pypi deployment workflows
3. the case for "pip bundle" (or not)

12 Chapter 5. Packaging Guide

 CHAPTER 6

Project Summaries

Page Status Complete

Last Reviewed 2013-10-31
Summaries for the most relevant projects in the space of Python installation and packaging.

6.1 pip

Docs | User list 1 | Dev list | Issues | Github | PyPI | irc:#pip

A tool for installing and managing Python packages.

6.2 virtualenv

Docs | User list | Dev list | Issues | Github | PyPI | irc:#pip

A tool for creating isolated Python environments.

6.3 distlib

Docs | Mailing list 2 | Issues | Bitbucket | PyPI

Distlib is a library which implements low-level functions that relate to packaging and distribution of Python software.
It consists in part of the functions in the packaging Python package, which was intended to be released as part of
Python 3.3, but was removed shortly before Python 3.3 entered beta testing.

6.4 setuptools

Docs | User list 2 | Dev list | Issues | Bitbucket | PyPI

1 pip was created by the same developer as virtualenv, and early on adopted the virtualenv mailing list, and it’s stuck ever since.
2 Multiple projects reuse the distutils-sig mailing list as their user list.

13
Python Packaging Guide, Release

setuptools is a collection of enhancements to the Python distutils that allow you to more easily build and distribute
Python packages, especially ones that have dependencies on other packages.
distribute was a fork of setuptools that was recently merged back into setuptools (in v0.7), thereby making setuptools
the primary choice for Python packaging.

6.5 distribute

Docs | Mailing list 2 | Issues | Bitbucket | PyPI

distribute was a fork of the setuptools project, and was intended to replace setuptools as the standard method for
working with Python module distributions.
distribute was recently merged back into setuptools (in v0.7), thereby making setuptools the primary choice for Python
packaging.

6.6 wheel

Docs | Mailing list 2 | Issues | Bitbucket | PyPI

Primarily, the wheel project offers the bdist_wheel setuptools extension for creating wheel distributions. Addi-
tionally, it offers it’s own command line utility for creating and installing wheels.

6.7 buildout

Docs | Mailing list 2 | Issues | PyPI | irc:#buildout

Buildout is a Python-based build system for creating, assembling and deploying applications from multiple parts, some
of which may be non-Python-based. It lets you create a buildout configuration and reproduce the same software later.

6.8 bento

Docs | Mailing list | Issues | Github | PyPI

Bento is a packaging tool solution for python software, targeted as an alternative to distutils, setuptools, distribute,
etc.... Bento’s philosophy is reproducibility, extensibility and simplicity (in that order).

6.9 conda
Docs
conda is an installation tool for managing Anaconda installations. Anaconda is a collection of powerful packages
for Python that enables large-scale data management, analysis, and visualization for Business Intelligence, Scientific
Analysis, Engineering, Machine Learning, and more.

14 Chapter 6. Project Summaries

 Python Packaging Guide, Release

6.10 Hashdist

Docs | Github
Hashdist is a library for building non-root software distributions. Hashdist is trying to be “the Debian of choice for
cases where Debian technology doesn’t work”. The best way for Pythonistas to think about Hashdist may be a more
powerful hybrid of virtualenv and buildout.

6.10. Hashdist 15
Python Packaging Guide, Release

16 Chapter 6. Project Summaries

 CHAPTER 7

PEP Summaries

Page Status Incomplete 1

Last Reviewed 2013-11-01
Summaries for the most relevant PEPs in the space of Python installation and packaging.

7.1 PEP376 Database of Installed Python Distributions

PEP Link PEP376

PEP Status Accepted
Summary Describes a new .dist-info directory structure to be used when installing distributions.
User Impact This has very little implication for users, except that it might help users to be aware of this
directory format if they go hunting through their site-packages for some reason, which we all end
up doing from time to time.
Implementation Currently, only the bdist_wheel extension from the wheel project creates distribu-
tions using this structure, although setuptools and pip are equipped to manage distributions installed
in this way.

7.2 PEP425 Compatibility Tags for Built Distributions

PEP Link PEP425

PEP Status Accepted

Note: A revision to this PEP is likely due to it not handling the variation within a specific plat-
form, e.g. the linux variation we see across the linux distros is not covered with the simple tag
“linux_x86_64”. Because of this, PyPI currently blocks uploading platform-specific wheels (ex-
cept for windows), and pip currently won’t install platform-specific wheels from PyPI (except for
windows).

1 Need to fill in missing information.

17
Python Packaging Guide, Release

Summary Specifies a tagging system to use in Binary Distribution file names. The motivation for the
system was to tag wheel distributions, which are covered in PEP427
User Impact As wheels become more common, users will notice the new tagging scheme in wheel file-
names.
Implementation The bdist_wheel setuptools extensions generates wheels using this scheme, and
pip’s wheel installer understands the scheme as of v1.4.

7.3 PEP427 The Wheel Binary Package Format 1.0

PEP Link PEP427

PEP Status Accepted
Summary
User Impact
Implementation

7.4 PEP438 Transitioning to release-file hosting on PyPI

PEP Link PEP438

PEP Status Accepted
Summary
User Impact
Implementation

7.5 PEP453 Explicit bootstrapping of pip in Python installations

PEP Link PEP453

PEP Status Accepted
Summary Proposes the inclusion of a method for explicitly bootstrapping pip as the default package
manager for Python.
User Impact pip will be available without users having to install it.
Implementation The goal is to have this for Python 3.4. PEP453 includes an integration timeline.

7.6 PEP426 Metadata for Python Software Packages 2.0

PEP Link PEP426

PEP Status Draft
Summary
User Impact

18 Chapter 7. PEP Summaries

 Python Packaging Guide, Release

Implementation

7.7 PEP440 Version Identification and Dependency Specification

PEP Link PEP427

PEP Status Draft
Summary
User Impact
Implementation

7.7. PEP440 Version Identification and Dependency Specification 19

Python Packaging Guide, Release

20 Chapter 7. PEP Summaries

 CHAPTER 8

The Future of Python Packaging

Page Status Incomplete 1

Last Reviewed 2013-11-01
The distutils cross-platform build and distribution system was added to the Python standard library in late 1998. This
means the current Python software distribution ecosystem is almost 15 years old, which poses a variety of challenges
to successful evolution.
The current attempt really started when the decision was made to remove the incomplete packaging project (also
known as distutils2) from the standard library prior to the release of Python 3.3.
While distutils2 itself is no longer under development, that project laid the foundations for many of the cur-
rent efforts (and also highlighted the fact that, while the setup.py install command is highly problematic,
setup.py is significantly more reasonable as an interface to a build system.

8.1 Overall Goal

The primary aim of the Python Packaging Authority is to provide a relatively easy to use software distribution infras-
tructure that is also fast, reliable and reasonably secure.
“Reasonably secure” is the aim, since backwards compatibility constraints prevent turning off some insecure legacy
features (like API access over HTTP) and the PyPI index operators only promise to deliver the bits to end users that
were uploaded by the original author. Whether or not those bits themselves are malicious is ultimately up to end users
to determine for themselves.

8.2 Panels, Presentations & Other Articles

In addition to this document, there have been some talks and presentations regarding current and future efforts related
to packaging.
• PyCon US, March 2013
– Directions in Packaging Q & A Panel (aka ”./setup.py install must die”)
• PyCon AU, July 2013
1 Many items need be linked and expanded so this can made more accessible to regular python users.

21
Python Packaging Guide, Release

– Nobody Expects the Python Packaging Authority

• Personal essays
– Nick Coghlan

8.3 Completed work

• Core PyPI infrastructure relocated to OSU/OSL (with significantly increased resources)

• Core packaging projects collected under the Python Packaging Authority accounts on GitHub and BitBucket
• distribute merged back into setuptools, and setuptools development migrated to BitBucket
• PyPI supports clients using verified SSL with standard cert bundles
• PyPI forces web users over to SSL
• easy_install and pip use verified SSL by default
• setuptools/easy_install support additional hashes beyond md5
• PEP 8 cleanup (including clarification of what constitutes an internal API)
• Fastly CDN enabled for PyPI (donated)
• Restructured the installation documentation on pip-installer.org to ensure setuptools and pip are clearly the
“base” of the bootstrapping hierarchy

8.4 Approved work (in progress)

• PEP 438 (Transitioning to PyPI file hosting)

• PEP 449 (Removal of the DNS based mirror autodiscovery)
• PEP 453 (explicit pip bootstrapping in the standard library)

8.5 Upcoming work (Python 3.4/pip 1.5 timeframe)

• improved handling of in-place pip upgrades on Windows

• improved handling of pip/setuptools/pkg_resources division of responsibility
• both pip and setuptools available as cross platform wheel files on PyPI

8.6 Upcoming work (post Python 3.4/pip 1.6 timeframe)

Experimental versions of items mentioned in this section may already be available.

• further proposals target pip 1.6 - decoupled from CPython release cycle
• eliminate pip dependency on setuptools
• metadata 2.0 (PEP 426/440)
• sdist 2.0 and wheel 1.1

22 Chapter 8. The Future of Python Packaging

 Python Packaging Guide, Release

• installation database format update

• revisit using The Update Framework (TUF) for end-to-end PyPI security

8.7 Independent activities & miscellaneous suggestions

• improved PyPI upload API (Donald’s working on this)

• migration from the legacy PyPI server (which has no automated regression tests!) to the new (properly tested)
Warehouse project (the preview is available at https://preview-pypi.python.org/ running off the live PyPI data)
• TUF-for-PyPI exploration (the TUF folks seems to have this well in hand)
• improved local PyPI hosting (especially devpi)
• getting this guide up to scratch, so the python.org docs can refer to it as the primary resource for developers
wanting to distribute or install Python packagers

8.7. Independent activities & miscellaneous suggestions 23

Python Packaging Guide, Release

24 Chapter 8. The Future of Python Packaging

 CHAPTER 9

A Packaging Timeline

Page Status Incomplete 1

Last Reviewed 2013-10-29
2013-06-09: The merge of setuptools and distribute was completed and released to PyPI. 2
2013-03-23: PyPA became the maintainer for the Python Packaging User Guide, which was forked from the “Hitch-
hiker’s Guide to Packaging”. 3
4 5
2013-03-15: Packaging Dev and User Summits were held at Pycon 2013 to share ideas on the future of packaging.
2013-03-14: The intention to merge setuptools and distribute was announced by their respective maintainers, PJ Eby
and Jason Coombs. 6
7
2013-03-09: pip began depending on distlib.
2013-03-02: distlib began releasing to PyPI.
2013-03-17: PEP425 and PEP427 were accepted. Together, they specify a built-package format for Python called
“wheel”.
8
2012-06-19: The effort to include “Distutils2/Packaging” in Python 3.3 was abandoned due lack of involvement.
2008: After some period of trying to open up the Setuptools project itself, some of these developers led by Tarek Ziade
decided to fork Setuptools. The fork was named Distribute.
2008: Ian Bicking created an alternative for easy_install called pip, also building on Setuptools.
2007: virtualenv was released. Ian Bicking drove one line of solutions: virtual-python, which evolved into workingenv,
which evolved into virtualenv in 2007. The concept behind this approach is to allow the developer to create as many
fully working Python environments as they like from a central system installation of Python. When the developer
activates the virtualenv, easy_install will install all packages into its the virtualenv’s site-packages. This allows you to
create a virtualenv per project and thus isolate each project from each other.
2006: Jim Fulton created Buildout, building on Setuptools and easy_install. Buildout can create an isolated project
environment like virtualenv does, but is more ambitious: the goal is to create a system for repeatable installations of
1 Missing some recent events. Some the older events could more brief.
2 http://mail.python.org/pipermail/distutils-sig/2013-June/021160.html
3 http://mail.python.org/pipermail/distutils-sig/2013-March/020224.html
4 https://us.pycon.org/2013/community/openspaces/packaginganddistributionminisummit/
5 http://www.pyvideo.org/video/1731/panel-directions-for-packaging
6 http://mail.python.org/pipermail/distutils-sig/2013-March/020127.html
7 https://github.com/pypa/pip/pull/834
8 http://mail.python.org/pipermail/python-dev/2012-June/120430.html

25
Python Packaging Guide, Release

potentially very complex projects. Instead of writing an INSTALL.txt that tells others who to install the prerequites
for a package (Python or not), with Buildout these prerequisites can be installed automatically.
2004: Phillip Eby started work on Setuptools in 2004. Setuptools is a whole range of extensions to Distutils such as
from a binary installation format (eggs), an automatic package installation tool, and the definition and declaration of
scripts for installation. Work continued throughout 2005 and 2006, and feature after feature was added to support a
whole range of advanced usage scenarios.
2003: The Python package index was up and running. The Python world now had a way to upload packages and
metadata to a central index. If we then manually downloaded a package we could install it using setup.py thanks to
Distutils.
2002: Richard Jones started work on the Python Package Index, PyPI. PyPI is also known as the Cheeseshop. The first
work on an implementation started, and PEP 301 that describes PyPI was also created then. Distutils was extended so
the metadata and packages themselves could be uploaded to this package index.
2001: The first step was to standardize the metadata that could be cataloged by any index of Python packages. Andrew
Kuchling drove the effort on this, culminating in PEP 241, later updated by PEP 314:
2000: We didn’t have a centralized index (or catalog) of packages yet, however. To work on this, the Catalog SIG was
started in the year
2000: Distutils was added to the Python standard library in Python 1.6. We now had a way to distribute and install
Python packages, if we did the distribution ourselves.
1998: The Distutils SIG (special interest group) was created. Greg Ward in the context of this discussion group started
to create Distutils about this time. Distutils allows you to structure your Python project so that it has a setup.py.
Through this setup.py you can issue a variety of commands, such as creating a tarball out of your project, or installing
your project. Distutils importantly also has infrastructure to help compiling C extensions for your Python package.

26 Chapter 9. A Packaging Timeline

 CHAPTER 10

Glossary

Page Status Incomplete 1

Last Reviewed 2013-10-31
Binary Distribution A Distribution format containing prebuilt files that only need to be moved to the correct location
on the target system. As Python is a dynamically bound cross-platform language, many so-called “binary”
distributions will contain only pure Python source code.
Distribution A Python distribution is a versioned archive file that contains Python packages, modules, and other
resource files that are used to distribute a Release. The distribution file is what an end-user will download from
the internet and install.
Distutils A standard package that comes with the Python Standard Library that has support for creating distributions.
setuptools provides enhancements to distutils, and is more commonly used than distutils by itself.
Egg A Binary Distribution format introduced by setuptools, which is being replaced by Wheel. For details, see The
Internal Structure of Python Eggs and Python Eggs
Extension Module A module written in the low-level language of the Python implementation: C/C++ for Python,
Java for Jython. Typically contained in a single dynamically loadable pre-compiled file, e.g. a shared object
(.so) file for Python extensions on Unix, a DLL (given the .pyd extension) for Python extensions on Windows,
or a Java class file for Jython extensions.
Known Good Set (KGS) A set of distributions at specified versions which are compatible with each other. Typically
a test suite will be run which passes all tests before a specific set of packages is declared a known good set. This
term is commonly used by frameworks and toolkits which are comprised of multiple individual distributions.
Module The basic unit of code reusability in Python, existing in one of two types: Pure Module, or Extension Module.
Package (Meaning #1) A directory containing an __init__.py file (ex. mypackage/__init__.py), and
also usually containing modules (possibly along with other packages). You can import a package: import
mypackage
Package (Meaning #2) A synonym for Distribution. It is common in Python to refer to a distribution using the term
“package”. While the two meanings of the term “package” is not always 100% unambigous, the context of the
term “package” is usually sufficient to distinguish the meaning of the word. For example, the python installation
tool pip is an acronym for “pip installs packages”. while technically the tool installs distributions. Even the site
where distributions are distributed at is called the “Python Package Index” (and not the “Python Distribution
Index”).
1 Although the current terms have been reviewed, there’s more terminology used by projects like pip and setuptools that needs to be added.

27
Python Packaging Guide, Release

Package Index A repository of distributions with a web interface to automate Distribution discovery and consump-
tion.
Project A library, framework, script, plugin, application, or collection of data or other resources, or some combina-
tion thereof.
Python projects must have unique names, which are registered on PyPI. Each project will then contain one or
more Releases, and each release may comprise one or more distributions.
Note that there is a strong convention to name a project after the name of the package that is imported to run that
project. However, this doesn’t have to hold true. It’s possible to install a distribution from the project ‘spam’
and have it provide a package importable only as ‘eggs’.
Pure Module A module written in Python and contained in a single .py file (and possibly associated .pyc and/or .pyo
files).
Python Packaging Authority (PyPA) PyPA is an informal working group that maintains some of the most relevant
projects for Python packaging. They host projects at https://github.com/pypa/ and https://bitbucket.org/pypa,
and discuss issues at https://groups.google.com/forum/#!forum/pypa-dev.
Python Package Index (PyPI) PyPI is the default Package Index for the Python community. It is open to all Python
developers to consume and distribute their distributions.
Release A snapshot of a Project at a particular point in time, denoted by a version identifier.
Making a release may entail the publishing of multiple Distributions. For example, if version 1.0 of a project
was released, it could be available in both a source distribution format and a Windows installer distribution
format.
Source Archive An archive containing the raw source code for a Release, prior to creation of an Source Distribution
or Binary Distribution.
Source Distribution (or “sdist”) A distribution format (usually generated using python setup.py sdist)
that provides metadata and the essential source files needed for installing by a tool like pip, or for generating a
Binary Distribution.
System Package A package provided in a format native to the operating system, e.g. an rpm or dpkg file.
Wheel A Binary Distribution format introduced by PEP427 The Wheel Binary Package Format 1.0, which is intended
to replace the Egg format. Wheel is currently supported by pip.
Working Set A collection of distributions available for importing. These are the distributions that are on the sys.path
variable. At most, one Distribution for a project is possible in a working set.

28 Chapter 10. Glossary

 CHAPTER 11

Additional Resources

Page Status Incomplete 1

Last Reviewed 2013-10-29
Additional Resources we deem might be helpful.
1. For those looking for a more comprehensive guide to “How do I publish my Python project in a way that will
make it as easy as possible for me to maintain and for others to contribute?”, then Jeff Knupp’s Open Sourcing
a Python Project the Right Way is an excellent guide that is up to date with the currently available tools (as of
September, 2013). Even for those not looking for a step-by-step guide, Jeff’s post provides some links to some
excellent resources.

1 So many links we could add here. We don’t have to vouch for every word in these links, just want to narrow things down more than users

googling.

29
Python Packaging Guide, Release

30 Chapter 11. Additional Resources

 CHAPTER 12

Credits

Page Status Incomplete 1

Last Reviewed 2013-10-29
Here’s the list of writers, editors, reviewers, and people who allowed some of their own content to be included in the
guide.
• Alex J. Burke
• Brett Cannon
• C. Titus Brown
• Carl Meyer
• Kevin Teague
• Jean-Paul Calderone
• John M. Gabriele
• Marcus Smith
• Martijn Faassen
• Michael Mulich
• Nick Coghlan
• Reinout van Rees
• Tarek Ziadé

1 Need to review the commit history for missing names.

31
Python Packaging Guide, Release

32 Chapter 12. Credits

 CHAPTER 13

License

Page Status Complete

Last Reviewed 2013-10-29
The Python Packaging User Guide is licensed under a Creative Commons Attribution-ShareAlike license:
http://creativecommons.org/licenses/by-sa/3.0/

33