Using poetry

poetry add sphinx-needs

Using pip

pip install sphinx-needs

If you wish to also use the plotting features of sphinx-needs (see needbar and needpie), you need to also install matplotlib, which is available via the plotting extra:

pip install sphinx-needs[plotting]


Prior version 1.0.1 the package was named sphinxcontrib-needs.

Using sources

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


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

extensions = ["sphinx_needs",]

For the full configuration, please read Configuration.


Prior version 1.0.1 the extensions was called sphinxcontrib.needs.

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. Make a new folder called utils inside your docs folder. Copy the plantuml.jar file into the utils folder.

  3. Install the plantuml sphinx extension: pip install sphinxcontrib-plantuml.

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

extensions = ['sphinxcontrib.plantuml',
  1. 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 do not store it inside your source version control system.

Using Docker

Sphinx-Needs is also available as a Docker Image.

See Sphinx-Needs Docker Image for the documentation and hints how to use it.