Distributing PyGraphics

PyGraphics uses distutils for installation/packaging.

This means that PyGraphics has a setup.py file at the top level. If you have the PyGraphics source code, and the setup.py file, then the command for installing PyGraphics is python setup.py install (if you’re root), or python setup.py install --user (if you’re not root and on python 2.6+).

This same file is used for all the other commands involved with packaging and distributing PyGraphics. It can create Windows installers, upload to the web, etc.

For more information on producing distributions, confer with the distutils documentation on distribution


Before creating a release distributable, be sure to update the versions. Version numbers can be found in setup.py and docs/conf.py. Update them as appropriate for the release.


setup.py can produces installers for various OSes. These can be used with the package manager to install software in a standard way.

Installers are not always the appropriate thing. In particular, on Linux, it’s better (i.e. works on more OSes) to distribute a source di-stribution.

On windows:

python setup.py bdist_msi

On RPM Linuxes:

python setup.py bdist_rpm

The resulting packaged distribution will be available in the dist directory that setup.py creates.

On OS X:

easy_install bdist_mpkg

In the root of the pygraphics repository:


PyGraphics requires a particular fork of Ampy. You can get the sources this way:

bzr export -r 14 ampy-jeanpierreda-r14 lp:~jeanpierreda/ampy/twisted-compat

There is another setup.py file inside ampy-jeanpierreda-r14. You can build platform-specific installers using the same method above.

To distribute, place ampy-1.2.3-py2.7-macosx.mpkg, PIL-1.1.7-python.org-32bit-py2.7-macosx.mpkg, pygame-1.9.1release-python.org-32bit-py2.7-macosx.mpkg, and PyGraphics-2.0-py2.7-macosx10.7.mpkg in the same folder, open Disk Utility, and select News->Disk Image from Folder. Name it “PyGraphicsInstaller” and upload it to PyPI.

Source distributions

A source distribution is just an archive file that contains all the source code. After it is unarchived, it should be installed via python setup.py install as described above.

The basic command for producing a source distribution is the following:

python setup.py sdist

On Windows, this will produce a .zip file. On Linux, this will produce a .tar.gz file. To produce a nondefault format, use the --format option to setup.py:

python setup.py sdist --format=zip,gztar # both .zip and .tar.gz

As with installer distributions, the resulting archives will be in the dist directory that setup.py creates.

Distributing the packages

Google Code has its own upload mechanism, if the files are to be hosted there, all the packages must be uploaded manually.

If, on the other hand, PyPI will be the distribution host, distutils has a built-in mechanism for uploading packages.

First, you need to be registered to PyPI, and listed on the PyGraphics administrators. After that, put your PyPI login information in a .pypirc file in your home directory, like this:


You’re set! In all the above setup.py commands, you can append upload to the command. For example:

python setup.py sdist --format=zip,gztar upload

This will automatically upload the resulting zip and tar.gz files to PyPI.


The documentation system is not made using distutils, but using Sphinx . Sphinx is also used for the official Python documentation.

In the docs directory of the PyGraphics project, you can create the html documentation with the following command:

make html

This tells sphinx to translate the documentation to HTML, and put it in the _build/html directory. You should manually put all the files in the html directory in a zip file. (Note: these should be at the top level of the zip file. Do not add the html directory itself.)

If you have the zip command line utility, the command is as follows:

cd _build/html
zip docs.zip -R "*"

Then, log in to PyPI and upload the documentation zip file. Once this is done, the documentation will be available for browsing at the PyPI website at http://packages.python.org/PyGraphics/

Table Of Contents

Previous topic

Developer Tutorials

Next topic

GUIs in PyGraphics: Working With AMP

This Page