skip to navigation
skip to content

Not Logged In

executor 4.4.1

Programmer friendly subprocess wrapper

The executor package/module is a simple wrapper for Python’s subprocess module that makes it very easy to handle subprocesses on UNIX systems with proper escaping of arguments and error checking. It’s currently tested on Python 2.6, 2.7, 3.4 and PyPy. For usage instructions please refer to the documentation.

Examples of usage

Below are some examples of how versatile the execute() function is.

Checking status codes

By default the status code of the external command is returned as a boolean:

>>> from executor import execute
>>> execute('true')

If an external command exits with a nonzero status code an exception is raised, this makes it easy to do the right thing (never forget to check the status code of an external command without having to write a lot of repetitive code):

>>> execute('false')
Traceback (most recent call last):
  File "executor/", line 124, in execute
  File "executor/", line 516, in start
  File "executor/", line 541, in wait
  File "executor/", line 568, in check_errors
    raise ExternalCommandFailed(self)
executor.ExternalCommandFailed: External command failed with exit code 1! (command: bash -c false)

The ExternalCommandFailed exception exposes command and returncode attributes. If you know a command is likely to exit with a nonzero status code and you want execute() to simply return a boolean you can do this instead:

>>> execute('false', check=False)

Providing input

Here’s how you can provide input to an external command:

>>> execute('tr a-z A-Z', input='Hello world from Python!\n')

Getting output

Getting the output of external commands is really easy as well:

>>> execute('hostname', capture=True)

Running commands as root

It’s also very easy to execute commands with super user privileges:

>>> execute('echo test > /etc/hostname', sudo=True)
[sudo] password for peter: **********
>>> execute('hostname', capture=True)

Enabling logging

If you’re wondering how prefixing the above command with sudo would end up being helpful, here’s how it works:

>>> import logging
>>> logging.basicConfig()
>>> logging.getLogger().setLevel(logging.DEBUG)
>>> execute('echo peter-macbook > /etc/hostname', sudo=True)
DEBUG:executor:Executing external command: sudo bash -c 'echo peter-macbook > /etc/hostname'

Running remote commands

To run a command on a remote system using SSH you can use the RemoteCommand class, it works as follows:

>>> from executor.ssh.client import RemoteCommand
>>> cmd = RemoteCommand('localhost', 'echo $SSH_CONNECTION', capture=True)
>>> cmd.start()
>>> cmd.output
' 57255 22'

Running remote commands concurrently

The foreach() function wraps the RemoteCommand and CommandPool classes to make it very easy to run a remote command concurrently on a group of hosts:

>>> from executor.ssh.client import foreach
>>> from pprint import pprint
>>> hosts = ['', '', '', '']
>>> commands = foreach(hosts, 'echo $SSH_CONNECTION')
>>> pprint([cmd.output for cmd in commands])
[' 57278 22',
 ' 52385 22',
 ' 49228 22',
 ' 40628 22']


The latest version of executor is available on PyPI and GitHub. The documentation is hosted on Read the Docs. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2015 Peter Odding.

File Type Py Version Uploaded on Size
executor-4.4.1.tar.gz (md5) Source 2015-08-30 31KB
  • Downloads (All Versions):
  • 0 downloads in the last day
  • 701 downloads in the last week
  • 3351 downloads in the last month