How To Add Custom Build Steps and Commands To

A script using distutils / setuptools is the standard way to package Python code. Often, however, we need to perform custom actions for code generation, running tests, profiling, or building documentation, etc., and we’d like to integrate these actions into In other words, we’d like to add custom steps to build or install, or add a new command altogether to

Let’s see how this is done.

Adding Custom Commands and Options

Let’s implement a custom command that runs Pylint on all Python files in our project. The high level idea is:

  1. Implement command as a subclass of distutils.cmd.Command;

  2. Add the newly defined command class to the cmdclass argument to setup().

To see this in action, let’s add the following to our

import distutils.cmd
import distutils.log
import setuptools
import subprocess

class PylintCommand(distutils.cmd.Command):
  """A custom command to run Pylint on all Python source files."""

  description = 'run Pylint on Python source files'
  user_options = [
      # The format is (long option, short option, description).
      ('pylint-rcfile=', None, 'path to Pylint config file'),

  def initialize_options(self):
    """Set default values for options."""
    # Each user option must be listed here with their default value.
    self.pylint_rcfile = ''

  def finalize_options(self):
    """Post-process options."""
    if self.pylint_rcfile:
      assert os.path.exists(self.pylint_rcfile), (
          'Pylint config file %s does not exist.' % self.pylint_rcfile)

  def run(self):
    """Run command."""
    command = ['/usr/bin/pylint']
    if self.pylint_rcfile:
      command.append('--rcfile=%s' % self.pylint_rcfile)
        'Running command: %s' % str(command),

        'pylint': PylintCommand,
    # Usual setup() args.
    # ...

Now, running python --help-commands will show:

Standard commands:
Extra commands:
  pylint: run Pylint on Python source files

We can now run the command we just defined with:

$ python pylint

…or with a custom option:

$ python pylint --pylint-rcfile=.pylintrc

To learn more, you can check out documentation on inheriting from distutils.cmd.Command as well as the source code of some built-in commands, such as build_py.

Adding Custom Steps to build

Let’s say we are really paranoid about code style and we’d like to run Pylint as part of build. We can do this in the following manner:

  1. Create a subclass of setuptools.command.build_py.build_py (or distutils.command.build_py.build_py if using distutils) that invokes our new Pylint command;

  2. Add the newly defined command class to the cmdclass argument to setup().

For example, we can implement the following in our

import setuptools.command.build_py

class BuildPyCommand(setuptools.command.build_py.build_py):
  """Custom build command."""

  def run(self):

        'pylint': PylintCommand,
        'build_py': BuildPyCommand,
    # Usual setup() args.
    # ...

For more examples, I encourage you to check out the setuptools source code.

About the author

I am a software engineer by profession and a passionate technology geek in my free time.