reStructuredText Table: Grid, Simple, CSV and List Tables

November 11, 2026 · 12 min read

reStructuredText Table Syntax: Grid, Simple, CSV and List Tables

A reStructuredText table comes in four forms. Grid tables are drawn with +, - and |, simple tables are ruled with =, and the csv-table and list-table directives skip drawing entirely. This page shows the source and rendered result of each, explains why grid tables break, and helps you pick the right one.

Four Ways to Write a reStructuredText Table

Docutils, the parser underneath Sphinx, gives you two ways to draw a reStructuredText table and two directives that build one for you. Grid and simple tables are ASCII art: the layout of characters in the source decides the rows and columns. The csv-table and list-table directives build the same HTML table from structured data, so you never line up a border.

FormMerged cellsMulti-line cellsBest for
Grid tableRows and columnsYes, any contentTables that need merged cells
Simple tableColumns onlyAll but the first columnShort reference tables
csv-tableNoneYes, quote the fieldSpreadsheet exports
list-tableNoneYes, any contentTables several people edit

If you're still choosing between Markdown and reStructuredText for a project, our Markdown vs reStructuredText comparison covers that decision. This page sticks to tables. For titles, roles and directives, see our reStructuredText example cheat sheet.

Grid Table Syntax: Borders, Header Rows and Spans

A grid table uses four characters. The hyphen - draws row separators, = marks the line under the header rows, | separates columns and + sits at every intersection. Each | and + must sit in exactly the same character column as the one above it.

+---------+------------------+---------------------------+
| Version | Status           | Notes                     |
+=========+==================+===========================+
| 3.0     | Supported        | Current release.          |
+---------+------------------+---------------------------+
| 2.4     | Security fixes   | - No new features         |
+---------+ only             | - Ends with the next      |
| 2.3     |                  |   major release           |
+---------+------------------+---------------------------+
| 1.x     | End of life, upgrade now                     |
+---------+------------------+---------------------------+

This renders as a three-column table with one header row. The Status and Notes cells for 2.4 stretch down over the 2.3 row, a row span, because the separator under 2.4 only crosses the first column. The 1.x row's last cell covers two columns, a column span, because no | divides it. In the HTML output, those spans are the same rowspan and colspan attributes you'd write to merge HTML table cells.

Each cell is a small document of its own, so the Notes cell holds a real bulleted list. Leave a blank line before and after the table and keep its left edge flush with the surrounding text. An indented table becomes part of a block quote.

Drawing that border by hand is slow. Fill in the rows in our ASCII table generator, choose its ascii style, and you get a +---+ table to adapt as a grid table skeleton. It needs two edits first. Change the rule under the header from - to =, and add a +---+ line between body rows, because without one Docutils merges those rows into a single row. The tool doesn't output merged cells, so add spans yourself.

Simple Table Syntax and Its First-Column Rule

Simple tables trade power for speed. You draw only horizontal rules of =: one on top, one under the header and one at the bottom. Column boundaries are gaps of at least one space in those rules, and two spaces is the recommended minimum. You also need two or more columns, so the parser doesn't mistake the table for a section title.

===========  =======  ============================
Setting      Default  Effect
===========  =======  ============================
numfig       False    Numbers captioned tables,
                      figures and code blocks.
smartquotes  True     Converts straight quotes to
                      typographic ones.
\            \        Row with empty first cells.
===========  =======  ============================

That produces a three-column table with three body rows. A line whose first column is blank continues the row above, which is how each Effect cell spans two source lines. The catch: first-column cells can only hold one line. To start a new row with an empty first cell, write \ (a backslash and a space) or an empty comment .. in it.

For a column span, underline the joined columns with -. The underline must cover every column and applies only to the row directly above it:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
=====  =====  ======

Here "Inputs" spans the first two columns of the header. Simple tables never support row spans. The rightmost column is unbounded, so text may run past the border, although the spec recommends making the rule long enough.

Why Do reStructuredText Grid Tables Break?

Docutils reads a grid table as a set of rectangles. Push one character out of line and the cells stop being rectangles, so the parser rejects the whole table. Plain Docutils prints the raw source into your output with an error, while Sphinx drops the table and logs the error during the build. Here the second body cell is one character too wide:

+----------+----------+
| Name     | Value    |
+==========+==========+
| width    | 80 chars  |
+----------+----------+

Docutils 0.22.4 reports this as an ERROR/3 system message:

Malformed table.
Right border not aligned or missing.

These are the usual causes:

  • Editing one cell. Lengthen a value and its | moves right, so every other row and +---+ line needs new padding.
  • Tabs. Docutils converts tabs to spaces with tab stops every 8th column, so an aligned-looking tab rarely lands on the border.
  • Wide characters. In our test, Docutils counted each Chinese or Japanese character as two columns. Pad by character count and the right border misses.
  • A literal | in a spanned cell. If it lines up exactly with a hidden column boundary, Docutils can read it as a border. The reStructuredText spec suggests shifting the text one space or adding a line to that row.

All four problems come from hand-aligned borders. The two directives below never need them, because commas or list markers define the structure instead of character positions.

How Do You Build a Table From CSV in reStructuredText?

Use the csv-table directive when your data already lives in a spreadsheet. The text after csv-table:: becomes the caption, and the indented content is ordinary CSV. Options go on the lines between the directive and a blank line.

.. csv-table:: Supported releases
   :header: "Version", "Status", "Notes"
   :widths: 15, 15, 50

   "3.0", "Supported", "Current release"
   "2.4", "Security fixes", "No new features, and support
   ends with the next major release"
   "1.x", "End of life", "Says ""upgrade now"" in the logs"

This renders a captioned three-column table with relative column widths of 15, 15 and 50. The 2.4 note spans two source lines yet stays in one cell, because line ends are allowed inside a quoted field. That's also the answer to wrapping text in a CSV cell: quote the field, and the HTML cell wraps long text like any other table cell. Two double quotes in a row produce one literal quote mark.

The options you'll use most, per the Docutils directives reference:

  • :header: adds a header row written as separate CSV, while :header-rows: treats the first N data rows as the header.
  • :delim: changes the separator to another character, or to the special values tab or space. Tabs only work in external files.
  • :file: or :url: loads the data from outside the document, as in :file: data/releases.csv.
  • :stub-columns: turns the first N columns into row headings.

Docutils flags :file: and :url: as potential security holes, and they can be switched off with the file_insertion_enabled setting. Docutils also doesn't check that every row has the same number of fields. It pads short rows with empty cells, so a missing comma shifts data silently.

list-table: The reStructuredText Table That Survives Edits

The list-table directive reads a uniform two-level bullet list. Each top-level item is a row, and each nested item is a cell. Uniform means every row has the same number of cells.

.. list-table:: Build commands
   :header-rows: 1
   :stub-columns: 1
   :widths: 20 40 40

   * - Target
     - Command
     - Notes
   * - HTML
     - ``make html``
     - Output lands in ``_build/html``.
   * - PDF
     - ``make latexpdf``
     - Needs a LaTeX install.

       Slower than HTML.

That renders a captioned table with a header row. The first column becomes row headings because of :stub-columns: 1, and the PDF Notes cell holds two separate paragraphs. If one row has fewer items, Docutils stops and reports that a uniform two-level bullet list was expected.

We prefer list-table for any table more than one person maintains. Each cell sits on its own line, so a git diff shows exactly which cell changed, and widening a cell never touches another row. The limitation is real, though: list-table has no row or column spans at all, and a wide table turns into a long vertical list in the source. Keep grid tables for the rare layout that needs merged cells.

How Do You Add a Caption to a reStructuredText Table?

For csv-table and list-table, the caption is the directive argument, as in both examples above. For grid and simple tables, wrap the table in the table directive and indent it:

.. table:: Truth table for AND
   :name: and-table
   :align: center
   :widths: auto

   =====  =====  =======
   A      B      A and B
   =====  =====  =======
   False  False  False
   True   True   True
   =====  =====  =======

The output gets the caption above the table, centered alignment and an HTML id of and-table. The :widths: option takes auto to let the browser or LaTeX decide, grid to copy the column widths from your source, or a list of integers.

In Sphinx, :name: also makes the table a cross-reference target. Set numfig = True in conf.py and Sphinx numbers every captioned table. A :numref: role pointing at and-table then renders as "Table 1". We checked this with Sphinx 9.0.4.

Need a monospaced column? Wrap each value in double backticks, as the make html cells in the list-table example do. That's inline literal markup, so the values render in a code font.

Sphinx Table Output: HTML, PDF and Python-Generated Tables

All four reStructuredText table forms render in Sphinx HTML builds, and your theme decides the borders, striping and padding. PDF output through LaTeX takes more care. Per the Sphinx directives docs, tables of up to 30 rows use tabulary, falling back to tabular when a cell holds a code block or nested table. Longer tables use longtable, which can break across pages.

  • Add :class: longtable to a table, csv-table or list-table directive to force longtable on a shorter table.
  • Put .. tabularcolumns:: before a table to give LaTeX its own column spec. It affects only the next table and only LaTeX output. If you set both it and :widths:, the LaTeX builder ignores :widths:.

If your rows live in Python, let a library draw the table. The tabulate package writes a simple table with tablefmt="rst":

from tabulate import tabulate

rows = [["HTML", "make html"], ["PDF", "make latexpdf"]]
print(tabulate(rows, headers=["Target", "Command"], tablefmt="rst"))

With tabulate 0.10.0 that prints:

========  =============
Target    Command
========  =============
HTML      make html
PDF       make latexpdf
========  =============

Switch to tablefmt="grid" and you get a grid table with an = header separator instead.

Some Sphinx projects are written in Markdown through MyST-Parser, whose table syntax follows GitHub Flavored Markdown pipe tables, with list-table and csv-table available as directives. Our Markdown table guide covers that syntax. MkDocs builds sites from Markdown files, so its tables are pipe tables too; see MkDocs Markdown.

A note on our own editor: its preview renders Markdown, not reStructuredText, so an RST table won't render as a table there.

Pick the reStructuredText table form by how the table will change. Use simple tables for quick reference data and grid tables only when you need merged cells. Reach for csv-table or list-table for anything you'll keep editing. Need to move content between Markdown and RST? The markup converter handles both directions in your browser. It isn't pandoc and doesn't fully support RST directives, so check any table it produces by hand.