All configurations take place in your project’s file.


Add sphinxcontrib.needs to your extensions:

extensions = ["sphinxcontrib.needs",]


All options starts with the prefix needs_ for this extension.


Set this option on False, if no needs should be documented inside the generated documentation.

Default: True:

needs_include_needs = False


This option defines the length of an automated generated ID (the length of the prefix does not count).

Default: 5:

needs_id_length = 3


The option allows the setup of own need types like bugs, user_stories and more.

By default it is set to:

needs_types = [dict(directive="req", title="Requirement", prefix="R_", color="#BFD8D2", style="node"),
               dict(directive="spec", title="Specification", prefix="S_", color="#FEDCD2", style="node"),
               dict(directive="impl", title="Implementation", prefix="I_", color="#DF744A", style="node"),
               dict(directive="test", title="Test Case", prefix="T_", color="#DCB239", style="node"),
               # Kept for backwards compatibility
               dict(directive="need", title="Need", prefix="N_", color="#9856a5", style="node")

needs_types must be a list of dictionaries, where each dictionary must contain the following items:

  • directive: Name of the directive. For instance “req”, which can be used via .. req:: in documents
  • title: Title, which is used as human readable name in lists
  • prefix: A prefix for generated IDs, to easily identify that an ID belongs to a specific type. Can also be “”
  • color: A color as hex value. Used in diagrams and some days maybe in other representations as well.
  • style: A plantuml node type, like node, artifact, frame, storage or database. See plantuml documentation for more.


The layout of needs can be fully customized by using jinja.

If nothing is set, the following default template is used:

.. _{{id}}:

{% if hide == false -%}
{{type_name}}: **{{title}}** ({{id}})
    {%- if status and  status|upper != "NONE" and not hide_status %}
    | status: {{status}}
    {%- endif -%}
    {%- if tags and not hide_tags %}
    | tags: {{tags|join("; ")}}
    {%- endif %}
    | links incoming: :need_incoming:`{{id}}`
    | links outgoing: :need_outgoing:`{{id}}`

    {{content|indent(4) }}

{% endif -%}

Available jinja variables are:

  • type
  • type_name
  • type_prefix
  • status
  • tags
  • id
  • links
  • title
  • content
  • hide
  • hide_tags
  • hide_status


You must add a reference like .. _{{id}}: to the template. Otherwise linking will not work!


This option allows to control the content of diagram elements, which get automatically generated by using .. needfilter:: and :layout: diagram.

This function is based on plantuml, so that each supported style can be used.

The rendered template is used inside the following plantuml syntax and must care about leaving the final string valid:

'node "YOUR_TEMPLATE" as need_id [[need_link]]'

By default the following template is used:



New in version 0.1.19.

Forces the user to set an ID for each need, which gets defined.

So no ID is autogenerated anymore, if this option is set to True:

needs_id_required = True

By default this option is set to False.

If an ID is missing sphinx throws the exception “NeedsNoIdException” and stops the build.


# With needs_id_required = True

.. req:: Working Requirement
   :id: R_001

.. req:: *Not* working, because :id: is not set.

# With needs_id_required = False

.. req:: This works now!


New in version 0.1.30.

Defines the location of a json file, which is used by the builder needs as input source. Default value: needs.json.