The online course, "Testing and Monitoring ML Model Deployments" is now live.

Using Python setuptools

A Basic Guide
Created: 11 December 2016

Python setuptools

The setuptools module deals with building and distributing Python packages. Technically, setuptools is not part of the Python standard library. However, the standard library package that is responsible for the same task, distutils, recommends using setuptools for distribution as it has greater functionality.

setuptools is complex. This guide focuses purely on the basics to get started.


Installing setuptools is slightly more effort than usual as you can’t use pip, check the install page for your OS requirements. In my case (OS X), I used curl to download

curl -o - | python


In your project root directory, create a file called Add the following to the script, adjusting to your project name/version etc.

from setuptools import setup, find_packages


You now have the bare minimum to use setuptools.


To run your file the command format is:

python <some_command> <options>

to view the available commands you can type:

python --help-commands

You can also review the command reference which gives a pretty average explanation of the available commands.

Key commands include:

  • sdist produces a raw source distribution (a gzipped tar file). Someone can just download this and run python directly.
  • bdist_egg generates a Python Egg (.egg) file for the project. This is needed if someone wants to use easy_install on your project.
  • sdist_wininst creates an .exe file to install your project on Windows.
  • upload uploads source and/or egg distributions to PyPI

For example, from my project root directory I can run:

python sdist

and I will then discover a new dist folder with a gzipped tar file of my project inside.

Note that in order to interact with PyPI (e.g. python sdist upload) you will first need to register an account

You need to supply your username and password for pypi-related commands. You can pass these as arguments to the setup command, but it’s easier to create a .pypirc for this purpose. On Linux, put this file in your $HOME directory (On Windows, you’ll need to set a HOME environ var to point to the .pypirc directory). The .pypirc looks like this:

servers = pypi

Adding functionality

We can add lots more to our file, for example:

    name = "your_project_name",
    version = "0.0.1",
    author = "Joe Bloggs",
    author_email = "",
    description = ("Foo bar baz"),
    license = "BSD",
    keywords = "example documentation tutorial",
    url = "",
    packages=['your_project_name', 'tests'],
        "Development Status :: 3 - Alpha",
        "Topic :: Utilities",
        "License :: OSI Approved :: BSD License",

Needless to say, this is just scratching the surface. Be sure to checkout the documentation.


The Python build system creates lots of intermediary files which you probably don’t want to commit to version control. Make sure you update your .gitignore file to include the following file types:

# Compiled python modules.

# Setuptools distribution directory.

# Python egg metadata, regenerated from source files by setuptools.

Optional Extras

You can configure setup() using a setup.cfg file. Typical uses include defining package metadata, and defining options usually supplied to the setup function.


name = my_package
version = attr: src.VERSION
description = My package description

zip_safe = False

You are now ready to distribute your Python project!