Runner: Executes shell commands

class invoke.runner.Result(stdout, stderr, exited, pty, pty_exception=None)

A container for information about the result of a command execution.

Result instances have the following attributes:

  • stdout: The subprocess’ standard output, as a multiline string.
  • stderr: Same as stdout but containing standard error (unless the process was invoked via a pty; see run.)
  • exited: An integer representing the subprocess’ exit/return code.
  • return_code: An alias to exited.
  • ok: A boolean equivalent to exited == 0.
  • failed: The inverse of ok: True if the program exited with a nonzero return code.
  • pty: A boolean describing whether the subprocess was invoked with a pty or not; see run.
  • pty_exception: Typically None, but may be an exception object if pty was True and run() had to swallow an apparently-spurious OSError. Solely for sanity checking/debugging purposes., warn=False, hide=None, pty=False, echo=False)

Execute command in a local subprocess, returning a Result object.

A Failure exception (which contains a reference to the Result that would otherwise have been returned) is raised if the subprocess terminates with a nonzero return code. This behavior may be disabled by setting warn=True.

To disable copying the subprocess’ stdout and/or stderr to the controlling terminal, specify hide='out' (or 'stdout'), hide='err' (or 'stderr') or hide='both' (or True). The default value is None, meaning to print everything; False will also disable hiding.


Stdout and stderr are always captured and stored in the Result object, regardless of hide‘s value.

By default, run connects directly to the invoked subprocess and reads its stdout/stderr streams. Some programs will buffer differently (or even behave differently) in this situation compared to using an actual terminal or pty. To use a pty, specify pty=True.


Due to their nature, ptys have a single output stream, so the ability to tell stdout apart from stderr is not possible when pty=True. As such, all output will appear on your local stdout and be captured into the stdout result attribute. Stderr and stderr will always be empty when pty=True.

run does not echo the commands it runs by default; to make it do so, say echo=True.

Previous topic

Parser: Core parsing state machine

Next topic

tasks: Task class & task-generating decorators

This Page