Jupyter Notebook Markdown Table: Syntax, Alignment and Headings

To make a table in a Jupyter Notebook, put the cell in Markdown mode and write the table with pipes (|) between columns and a row of hyphens under the header row. The notebook documentation states that the Notebook web app supports GitHub flavored Markdown, so GitHub’s table rules are the ones to follow. This guide puts those rules next to the heading syntax, so one page covers tables, headings and a short formatting cheat sheet.

What Markdown cells are used for in research notebooks

Per the Jupyter Notebook documentation, text is added to a notebook with Markdown cells. They keep explanatory text and tables next to the code. For the Python environment side, see Anaconda for Jupyter Notebook; for notebook add-ons, see Jupyter Notebook extensions.

Switch a cell to Markdown

The documentation says a cell is switched to Markdown through the Cell menu, through the toolbar, or with the m key. Once the cell is in Markdown mode, whatever you type is read as Markdown rather than code.

Create a Markdown table step by step

1. Switch the cell to Markdown (above).
2. Type the header row, with a pipe between column names.
3. On the next line, type a row of hyphens separated by pipes. GitHub’s documentation requires at least three hyphens in each header column.
4. Type one line per data row, again with pipes between cells.
5. Leave a blank line before the table if there is any text above it. GitHub’s documentation states that a blank line must precede the table.
6. Run the cell.

The Jupyter documentation’s own example is a three-line table:

| This | is   |
|------|------|
|   a  | table|

GitHub’s example shows the same pattern with longer header text:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |

GitHub’s documentation notes that the outer pipes are optional, though keeping them makes the table easier to read in the cell.

Align table columns

Alignment is set with colons in the hyphen row. Per GitHub’s documentation, :--- aligns left, :---: centers and ---: aligns right.

| Sample | Group | Count |
| :----- | :---: | ----: |
| S1     | A     | 12    |
| S2     | B     | 140   |

In that example, the Sample column is left-aligned, Group is centered and Count is right-aligned, which keeps numbers lined up for comparison.

Show a pipe character inside a table cell

GitHub’s documentation says to put a backslash before a pipe that should appear as text, written as \|. Without it, the pipe is read as a column break and shifts the cells after it.

Headings in Jupyter Notebook

The Jupyter documentation states that a heading is made by starting a line with one or more # characters followed by a space. Its examples are # Heading 1 and ## Heading 2.1. Headings are sometimes called headers in searches; in a Markdown cell they are the same thing, while the header row of a table is the first row above the hyphen line.

# Heading 1
## Heading 2.1

Markdown formatting cheat sheet for notebooks

This is a short reference limited to syntax the two official pages below state.

You want	Write this in a Markdown cell	Source
Heading	# Heading 1 (hash, then a space)	Jupyter Notebook docs
Table	Pipes between cells, hyphen row under the header, blank line before	GitHub docs
Column alignment	:---, :---:, ---: in the hyphen row	GitHub docs
Literal pipe in a cell	\|	GitHub docs
Code block	Triple backticks (GitHub flavored Markdown)	Jupyter Notebook docs
Inline math	Dollar signs around the expression, $ ... $	Jupyter Notebook docs
Math on its own line	\begin{equation} … \end{equation}	Jupyter Notebook docs

Why a table does not render

• The cell is still in code mode. The pipes appear as plain text. Switch the cell to Markdown.
• No blank line before the table. GitHub’s documentation requires one.
• Fewer than three hyphens in a header column. The hyphen row needs at least three per column.
• An unescaped pipe inside a cell. Write \| so it is not read as a column break.

Alternatives to a pipe table

Two ways to put a table in a Markdown cell:

Option	How it works	Source
Pipe table	Plain Markdown syntax covered above	GitHub docs, Jupyter Notebook docs
HTML table	The Jupyter documentation describes Markdown as a superset of HTML, so HTML tables can be added in a Markdown cell	Jupyter Notebook docs

If your notebook is part of a larger write-up, citations in Quarto, R Markdown and Pandoc covers Markdown-based documents, Quarto vs R Markdown compares the two, and a README template shows another place Markdown tables are used to document a project. To weigh hosted against local notebooks, see Google Colab vs Jupyter Notebook.

FAQ

How do I make a table in a Jupyter Notebook?

Switch the cell to Markdown, write the header row with pipes, add a hyphen row with at least three hyphens per column, then the data rows, and run the cell.

How do I make a heading in Jupyter Notebook?

Start a line in a Markdown cell with one or more # characters followed by a space, for example # Heading 1.

How do I align a column in a Markdown table?

Add colons to the hyphen row: :--- for left, :---: for center and ---: for right.

Does Jupyter Notebook support GitHub flavored Markdown?

Yes. The Jupyter Notebook documentation states that the Notebook web app supports GitHub flavored Markdown, including triple backticks for code blocks.

Can I put an HTML table in a Markdown cell?

Yes. The documentation describes Markdown as a superset of HTML, so HTML tables can be added.

Sources

• Jupyter Notebook documentation, Working With Markdown Cells (checked 2026-10-29)
• GitHub Docs, Organizing information with tables (checked 2026-10-29)