Sphinx Program Output Extension

0.19 · active · verified Thu Apr 16

sphinxcontrib-programoutput is a Sphinx extension that enables the literal insertion of arbitrary command output into documentation. This helps maintain up-to-date command examples. The current version is 0.19, with releases occurring on an irregular but active cadence, most recently in February 2026.

Common errors

```
ERROR: Unknown directive type "program-output"
```
cause The `sphinxcontrib-programoutput` extension has not been correctly added to the `extensions` list in your Sphinx `conf.py` file. Sphinx cannot find or recognize the directive.

fix Edit your `conf.py` file and add `'sphinxcontrib.programoutput'` to the `extensions` list: `extensions = ['sphinxcontrib.programoutput', ...]`. Make sure there are no typos.
```
ERROR: Command 'my_command' failed: [Errno 2] No such file or directory
```
cause The command specified in `.. program-output::` or `.. command-output::` cannot be found in the PATH of the environment where Sphinx is being built, or the `cwd` option is pointing to an incorrect directory, or the command itself is not executable. This often occurs when building documentation in a different environment (e.g., CI/CD, ReadTheDocs) than local development.

fix Ensure the command is installed and available in the execution environment's PATH. If it's a script from your project, ensure `cwd` is set correctly to the directory containing the script, or provide the full path to the executable. Verify Python virtual environments are correctly activated during the Sphinx build process.
```
ImportError: No module named 'pbr.version'
```
cause This specific `ImportError` (or similar for other modules) within `conf.py` when using `sphinxcontrib-programoutput` often indicates that Sphinx is not being run within the correct Python virtual environment that contains all project dependencies, including those needed for `conf.py` itself or by `programoutput`'s execution.

fix Activate your project's virtual environment before running `sphinx-build`. For automated builds (CI/CD, ReadTheDocs), ensure the build process correctly activates the environment or installs all necessary dependencies.

Warnings

breaking Version 0.18 significantly updated its Python and Sphinx requirements. It dropped support for Python versions older than 3.8 and now effectively requires Sphinx 5.0+ and docutils 0.18.1+. Projects on older Python or Sphinx versions will need to upgrade or stick to programoutput < 0.18.
Fix: Upgrade Python to 3.8+ and Sphinx to 5.0+ (and docutils to 0.18.1+), or pin `sphinxcontrib-programoutput` to a version prior to 0.18 (e.g., `sphinxcontrib-programoutput<0.18`).
gotcha By default, `sphinxcontrib-programoutput` does not interpret ANSI escape codes for coloring. To enable this, you must explicitly enable the `sphinxcontrib.ansi` extension, ensure you are on Python 3.10+, and set the `programoutput_use_ansi` configuration value to `True`.
Fix: Add `'sphinxcontrib.ansi'` to your `extensions` list in `conf.py`, set `programoutput_use_ansi = True`, and ensure your Python environment is 3.10+ if using this feature. Install `sphinxcontrib-ansi` if not already present.
gotcha Commands are executed in the top-level source directory by default. When using the `cwd` option, a relative path is interpreted relative to the *current source file*, while an absolute path is relative to the *root of the source directory*. Misunderstanding this can lead to 'file not found' errors.
Fix: Carefully specify `cwd` paths. For reliability, consider using absolute paths relative to the Sphinx project root (e.g., via `os.path.join(self.env.srcdir, 'my_relative_path')` if in a custom builder, or just absolute paths if the environment allows for it).
gotcha If a command returns a non-zero exit code, `sphinxcontrib-programoutput` by default emits a build warning. If you intend a command to fail (e.g., demonstrating error handling), this warning can be suppressed or inverted using the `:returncode:` option.
Fix: For commands expected to fail with a specific exit code, add `:returncode: N` (where N is the expected code) to the directive. For example, `.. program-output:: my_failing_command :returncode: 1`.

Install

pip install sphinxcontrib-programoutput Install from PyPI

Imports

sphinxcontrib.programoutput
wrong:
```
import sphinxcontrib.programoutput
```
correct:
```
extensions = ['sphinxcontrib.programoutput'] # in conf.py
```
This is a Sphinx extension, not a regular Python module to be imported directly into a Python script. It's enabled by adding its name to the 'extensions' list in Sphinx's conf.py configuration file.

Quickstart

After installation, enable the extension by adding 'sphinxcontrib.programoutput' to the `extensions` list in your Sphinx `conf.py`. Then, use the `.. program-output::` or `.. command-output::` reStructuredText directives in your documentation files to include command output. `command-output` mimics a shell session, including the command itself. Options like `cwd` (current working directory), `ellipsis` (to shorten output), `nostderr` (to hide stderr), `shell` (to pass command to system shell), and `returncode` (to expect specific exit codes) are available.

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinxcontrib.programoutput'
]

# Your_Document.rst

.. program-output:: python -V
   :shell:

.. command-output:: python -c "print('Hello from Python!')"

# Example with options
.. program-output:: git log -1
   :cwd: .
   :ellipsis: 2,-1

view raw JSON →