This document is being retained solely until the
independently covers all of the relevant information currently included here.
This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you’re looking for information on installing Python modules, you should refer to the Installing Python Modules (Legacy version) chapter.
Using the Distutils is quite simple, both for module developers and for users/administrators installing third-party modules. As a developer, your responsibilities (apart from writing solid, well-documented and well-tested code, of course!) are:
Each of these tasks is covered in this document.
Not all module developers have access to a multitude of platforms, so it’s not always feasible to expect them to create a multitude of built distributions. It is hoped that a class of intermediaries, called packagers, will arise to address this need. Packagers will take source distributions released by module developers, build them on one or more platforms, and release the resulting built distributions. Thus, users on the most popular platforms will be able to install most popular Python module distributions in the most natural way for their platform, without having to run a single setup script or compile a line of code.
The setup script is usually quite simple, although since it’s written in Python, there are no arbitrary limits to what you can do with it, though you should be careful about putting arbitrarily expensive operations in your setup script. Unlike, say, Autoconf-style configure scripts, the setup script may be run multiple times in the course of building and installing your module distribution.
If all you want to do is distribute a module called
foo, contained in a
foo.py, then your setup script can be as simple as this:
from distutils.core import setup setup(name='foo', version='1.0', py_modules=['foo'], )
To create a source distribution for this module, you would create a setup
setup.py, containing the above code, and run this command from a
python setup.py sdist
For Windows, open a command prompt window () and change the command to:
sdist will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script
setup.py, and your module
The archive file will be named
will unpack into a directory
If an end-user wishes to install your
foo module, all they have to do is
.zip), unpack it, and—from the
python setup.py install
which will ultimately copy
foo.py to the appropriate directory for
third-party modules in their Python installation.
This simple example demonstrates some fundamental concepts of the Distutils. First, both developers and installers have the same basic user interface, i.e. the setup script. The difference is which Distutils commands they use: the sdist command is almost exclusively for module developers, while install is more often for installers (although most developers will want to install their own code occasionally).
If you want to make things really easy for your users, you can create one or more built distributions for them. For instance, if you are running on a Windows machine, and want to make things easy for other Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the bdist_wininst command. For example:
python setup.py bdist_wininst
will create an executable installer,
foo-1.0.win32.exe, in the current
Other useful built distribution formats are RPM, implemented by the
bdist_rpm command, Solaris pkgtool
(bdist_pkgtool), and HP-UX swinstall
(bdist_sdux). For example, the following command will create an RPM
python setup.py bdist_rpm
(The bdist_rpm command uses the rpm executable, therefore this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by running
python setup.py bdist --help-formats
If you’re reading this document, you probably have a good idea of what modules, extensions, and so forth are. Nevertheless, just to be sure that everyone is operating from a common starting point, we offer the following glossary of common Python terms:
.pyfile (and possibly associated
.pycfiles). Sometimes referred to as a “pure module.”
.so) file for Python extensions on Unix, a DLL (given the
.pydextension) for Python extensions on Windows, or a Java class file for Jython extensions. (Note that currently, the Distutils only handles C/C++ extensions for Python.)
__init__.pyfile. But we have to call it something.) The vast majority of the standard library is in the root package, as are many small, standalone third-party modules that don’t belong to a larger module collection. Unlike regular packages, modules in the root package can be found in many directories: in fact, every directory listed in
sys.pathcontributes modules to the root package.
The following terms apply more specifically to the domain of distributing Python modules using the Distutils:
setup.pywill be run from this directory.