Using poetry

poetry add sphinxcontrib-needs

Using pip

pip install sphinxcontrib-needs

Using sources

git clone
cd sphinxcontrib-needs
pip install .
# or
poetry install


For final activation, please add sphinxcontrib.needs to the project’s extension list of your file:

extensions = ["sphinxcontrib.needs",]

For the full configuration, please read Configuration.

PlantUML support

needflow uses PlantUML and the Sphinx-extension sphinxcontrib-plantuml for generating the flows.

Both must be available and correctly configured to work.

Install PlantUML

  1. Download the latest version of the plantuml.jar file:

  2. Inside your docs folder create a folder called utils and copy plantuml.jar into it.

  3. Install sphinx support: pip install sphinxcontrib-plantuml.

  4. Add sphinxcontrib.plantuml to the sphinx extension list in

    extensions = ['sphinxcontrib.plantuml',
  5. Configure plantuml in

    on_rtd = os.environ.get('READTHEDOCS') == 'True'
    if on_rtd:
        plantuml = 'java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar'
        plantuml = 'java -jar %s' % os.path.join(os.path.dirname(__file__), "utils", "plantuml.jar"))
    plantuml_output_format = 'png'

The final configuration contains already a setup for building and deploying the documentation on ReadTheDocs.

ReadTheDocs provides plantuml.jar already on their system, so there is no need to store it inside your source version control system.

Using docker

Sphinx-Needs got also dockerized by Till Witt.

See for actual documentation and hints how to use it.