desub is a Python module to work with a detached subprocess.

This is useful for making a web interface (or whatever) to monitor a process running in the background. You can start a process from a web request and serve subsequent requests to report status on and show output for the process you started earlier.

Think of it as a way to monitor a long running command without having to manage PIDs yourself. You can either start or join a command (same executable, same args). Desub is not designed for running multiple instances of the same command. You can just use a regular subprocess for that.


pip install desub

This pulls in psutil as a requirement.


desub.join(cmd_args, **kw)

Join a subprocess or start one if it’s not running.

The return value is a desub.Desub object.

Start by joining a command that may or may not already be running.

>>> proc = desub.join(['python', 'tests/cmd/'])

There will only ever be one instance of that command running unless you specify a custom root. Check to see if the command is running:

>>> proc.is_running()

OK. It’s not running, so start it up:

>>> proc.start()
>>> proc.is_running()
>>> type(
<type 'int'>

Fetch the output:


Stop the command, if you want to:

>>> proc.stop()
>>> proc.is_running()

When you read the output of a stopped command, that’s the output from a subsequent run.

class desub.Desub(cmd_args, **kw)

A detached subprocess.

This object represents a command with cmd_args that may or may not be running yet. Two processes can be running at the same time but only if their args are different or if their roots are different.

The interface is similar to subprocess.Popen when appropriate. All extra keyword arguments are passed into the Popen constructor.

Keyword arguments

The root directory to store subprocess artifacts like a PID file and stdout/stderr logs. By default this is ~/.desub.



The integer PID of the subprocess or None.


An open read-only file to stdout.


An open read-only file to stderr.


Start the subprocess.


Stop the subprocess.

Keyword Arguments

Time in seconds to wait for a process and its children to exit.

True if the subprocess is running.

If it’s a zombie then we call desub.Desub.stop() to kill it with fire and return False.


Hello! To work on this module, check out the source from git and be sure you have the tox tool. To run the test suite, cd into the root and type:


This will run all tests in a virtualenv using the supported versions of Python.

To the build the docs run:

pip install -r docs/requirements.txt
make -C docs html

The issue tracker can be found on github.

Project Versions

Table Of Contents

This Page