Sphinx error: “list-table” widths do not match the number of columns in table

Did you Sphinx documentation project has failed with the error “list-table” widths do not match the number of columns in table? This guide provides an explanation and solution to resolve the issue.

Symptom

Sphinx build failed with the error similar to:

WARNING: "list-table" widths do not match the number of columns in table (3).

Worry-free Sphinx?

Documatt app is a Sphinx-based tool which hides its complexity with free hosting for your books and docs.

Try free 14 day trial Watch the demo

Reason

Table created with list-table directive, can have optional option :widths: that adjust columns’ widths. Above warning means :widths: is invalid because it define widths for different number of columns than the table has. The number of columns in the table is in parenthesis.

Example

The following is 2 rows x 3 columns table. Unfortunately, :widths: option contains only widths for 2 columns.

.. list-table::
   :widths: 50, 50

   * - row 1, column 1
     - row 1, column 2
     - row 1, column 3
   * - row 2, column 1
     - row 2, column 2
     - row 2, column 3

Solution

For example, we want the equal width columns. Width must be specified as integer. In this case, we use width of 33.

.. list-table::
   :widths: 33, 33, 33

   * - row 1, column 1
     - row 1, column 2
     - row 1, column 3
   * - row 2, column 1
     - row 2, column 2
     - row 2, column 3