python-tabulate

Pretty-print tabular data in Python, a library and a command-line utility.

The main use cases of the library are:

printing small tables without hassle: just one function call, formatting is guided by the data itself
authoring tabular data for lightweight plain-text markup: multiple output formats suitable for further editing or transformation
readable presentation of mixed textual and numeric data: smart column alignment, configurable number formatting, alignment by a decimal point

Installation

To install the Python library and the command line utility, run:

pip install tabulate

The command line utility will be installed as tabulate to bin on Linux (e.g. /usr/bin); or as tabulate.exe to Scripts in your Python installation on Windows (e.g. C:\Python39\Scripts\tabulate.exe).

You may consider installing the library only for the current user:

pip install tabulate --user

In this case the command line utility will be installed to ~/.local/bin/tabulate on Linux and to %APPDATA%\Python\Scripts\tabulate.exe on Windows.

To install just the library on Unix-like operating systems:

TABULATE_INSTALL=lib-only pip install tabulate

On Windows:

set TABULATE_INSTALL=lib-only
pip install tabulate

Build status

Library usage

The module provides just one function, tabulate, which takes a list of lists or another tabular data type as the first argument, and outputs a nicely formatted plain-text table:

>>> from tabulate import tabulate

>>> table = [["Sun",696000,1989100000],["Earth",6371,5973.6],
...          ["Moon",1737,73.5],["Mars",3390,641.85]]
>>> print(tabulate(table))
-----  ------  -------------
Sun    696000     1.9891e+09
Earth    6371  5973.6
Moon     1737    73.5
Mars     3390   641.85
-----  ------  -------------

The following tabular data types are supported:

list of lists or another iterable of iterables
list or another iterable of dicts (keys as columns)
dict of iterables (keys as columns)
list of dataclasses (Python 3.7+ only, field names as columns)
two-dimensional NumPy array
NumPy record arrays (names as columns)
pandas.DataFrame

Tabulate is a Python3 library.

Headers

The second optional argument named headers defines a list of column headers to be used:

>>> print(tabulate(table, headers=["Planet","R (km)", "mass (x 10^29 kg)"]))
Planet      R (km)    mass (x 10^29 kg)
--------  --------  -------------------
Sun         696000           1.9891e+09
Earth         6371        5973.6
Moon          1737          73.5
Mars          3390         641.85

If headers="firstrow", then the first row of data is used:

>>> print(tabulate([["Name","Age"],["Alice",24],["Bob",19]],
...                headers="firstrow"))
Name      Age
------  -----
Alice      24
Bob        19

If headers="keys", then the keys of a dictionary/dataframe, or column indices are used. It also works for NumPy record arrays and lists of dictionaries or named tuples:

>>> print(tabulate({"Name": ["Alice", "Bob"],
...                 "Age": [24, 19]}, headers="keys"))
  Age  Name
-----  ------
   24  Alice
   19  Bob

Row Indices

By default, only pandas.DataFrame tables have an additional column called row index. To add a similar column to any other type of table, pass showindex="always" or showindex=True argument to tabulate(). To suppress row indices for all types of data, pass showindex="never" or showindex=False. To add a custom row index column, pass showindex=rowIDs, where rowIDs is some iterable:

>>> print(tabulate([["F",24],["M",19]], showindex="always"))
-  -  --
0  F  24
1  M  19
-  -  --

Table format

There is more than one way to format a table in plain text. The third optional argument named tablefmt defines how the table is formatted.

Supported table formats are:

"plain"
"simple"
"github"
"grid"
"simple_grid"
"rounded_grid"
"heavy_grid"
"mixed_grid"
"double_grid"
"fancy_grid"
"outline"
"simple_outline"
"rounded_outline"
"heavy_outline"
"mixed_outline"
"double_outline"
"fancy_outline"
"pipe"
"orgtbl"
"asciidoc"
"jira"
"presto"
"pretty"
"psql"
"rst"
"mediawiki"
"moinmoin"
"youtrack"
"html"
"unsafehtml"
"latex"
"latex_raw"
"latex_booktabs"
"latex_longtable"
"textile"
"tsv"

plain tables do not use any pseudo-graphics to draw lines:

>>> table = [["spam",42],["eggs",451],["bacon",0]]
>>> headers = ["item", "qty"]
>>> print(tabulate(table, headers, tablefmt="plain"))
item      qty
spam       42
eggs      451
bacon       0

simple is the default format (the default may change in future versions). It corresponds to simple_tables in Pandoc Markdown extensions:

>>> print(tabulate(table, headers, tablefmt="simple"))
item      qty
------  -----
spam       42
eggs      451
bacon       0

github follows the conventions of GitHub flavored Markdown. It corresponds to the pipe format without alignment colons:

>>> print(tabulate(table, headers, tablefmt="github"))
| item   | qty   |
|--------|-------|
| spam   | 42    |
| eggs   | 451   |
| bacon  | 0     |

grid is like tables formatted by Emacs' table.el package. It corresponds to grid_tables in Pandoc Markdown extensions:

>>> print(tabulate(table, headers, tablefmt="grid"))
+--------+-------+
| item   |   qty |
+========+=======+
| spam   |    42 |
+--------+-------+
| eggs   |   451 |
+--------+-------+
| bacon  |     0 |
+--------+-------+

simple_grid draws a grid using single-line box-drawing characters:

>>> print(tabulate(table, headers, tablefmt="simple_grid"))
┌────────┬───────┐
│ item   │   qty │
├────────┼───────┤
│ spam   │    42 │
├────────┼───────┤
│ eggs   │   451 │
├────────┼───────┤
│ bacon  │     0 │
└────────┴───────┘

rounded_grid draws a grid using single-line box-drawing characters with rounded corners:

>>> print(tabulate(table, headers, tablefmt="rounded_grid"))
╭────────┬───────╮
│ item   │   qty │
├────────┼───────┤
│ spam   │    42 │
├────────┼───────┤
│ eggs   │   451 │
├────────┼───────┤
│ bacon  │     0 │
╰────────┴───────╯

heavy_grid draws a grid using bold (thick) single-line box-drawing characters:

>>> print(tabulate(table, headers, tablefmt="heavy_grid"))
┏━━━━━━━━┳━━━━━━━┓
┃ item   ┃   qty ┃
┣━━━━━━━━╋━━━━━━━┫
┃ spam   ┃    42 ┃
┣━━━━━━━━╋━━━━━━━┫
┃ eggs   ┃   451 ┃
┣━━━━━━━━╋━━━━━━━┫
┃ bacon  ┃     0 ┃
┗━━━━━━━━┻━━━━━━━┛

mixed_grid draws a grid using a mix of light (thin) and heavy (thick) lines box-drawing characters:

>>> print(tabulate(table, headers, tablefmt="mixed_grid"))
┍━━━━━━━━┯━━━━━━━┑
│ item   │   qty │
┝━━━━━━━━┿━━━━━━━┥
│ spam   │    42 │
├────────┼───────┤
│ eggs   │   451 │
├────────┼───────┤
│ bacon  │     0 │
┕━━━━━━━━┷━━━━━━━┙

double_grid draws a grid using double-line box-drawing characters:

>>> print(tabulate(table, headers, tablefmt="double_grid"))
╔════════╦═══════╗
║ item   ║   qty ║
╠════════╬═══════╣
║ spam   ║    42 ║
╠════════╬═══════╣
║ eggs   ║   451 ║
╠════════╬═══════╣
║ bacon  ║     0 ║
╚════════╩═══════╝

fancy_grid draws a grid using a mix of single and double-line box-drawing characters:

>>> print(tabulate(table, headers, tablefmt="fancy_grid"))
╒════════╤═══════╕
│ item   │   qty │
╞════════╪═══════╡
│ spam   │    42 │
├────────┼───────┤
│ eggs   │   451 │
├────────┼───────┤
│ bacon  │     0 │
╘════════╧═══════╛

outline is the same as the grid format but doesn't draw lines between rows:

>>> print(tabulate(table, headers, tablefmt="outline"))
+--------+-------+
| item   |   qty |
+========+=======+
| spam   |    42 |
| eggs   |   451 |
| bacon  |     0 |
+--------+-------+

simple_outline is the same as the simple_grid format but doesn't draw lines between rows:

>>> print(tabulate(table, headers, tablefmt="simple_outline"))
┌────────┬───────┐
│ item   │   qty │
├────────┼───────┤
│ spam   │    42 │
│ eggs   │   451 │
│ bacon  │     0 │
└────────┴───────┘

rounded_outline is the same as the rounded_grid format but doesn't draw lines between rows:

>>> print(tabulate(table, headers, tablefmt="rounded_outline"))
╭────────┬───────╮
│ item   │   qty │
├────────┼───────┤
│ spam   │    42 │
│ eggs   │   451 │
│ bacon  │     0 │
╰────────┴───────╯

heavy_outline is the same as the heavy_grid format but doesn't draw lines between rows:

>>> print(tabulate(table, headers, tablefmt="heavy_outline"))
┏━━━━━━━━┳━━━━━━━┓
┃ item   ┃   qty ┃
┣━━━━━━━━╋━━━━━━━┫
┃ spam   ┃    42 ┃
┃ eggs   ┃   451 ┃
┃ bacon  ┃     0 ┃
┗━━━━━━━━┻━━━━━━━┛

mixed_outline is the same as the mixed_grid format but doesn't draw lines between rows:

>>> print(tabulate(table, headers, tablefmt="mixed_outline"))
┍━━━━━━━━┯━━━━━━━┑
│ item   │   qty │
┝━━━━━━━━┿━━━━━━━┥
│ spam   │    42 │
│ eggs   │   451 │
│ bacon  │     0 │
┕━━━━━━━━┷━━━━━━━┙

double_outline is the same as the double_grid format but doesn't draw lines betwee

tabulate

Description