How to convert a Pandas DataFrame to a Markdown Table

# Table of Contents

# How to convert a Pandas DataFrame to a Markdown Table

Use the DataFrame.to_markdown() method to convert a Pandas DataFrame to a markdown table.

The method returns the DataFrame in a markdown-friendly format, as a string.

main.py

Copied!
import pandas as pd

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = df.to_markdown()

print(markdown_table)

The code for this article is available on GitHub

Running the code sample produces the following output.

shell

Copied!
|    | first_name   |   salary |   experience |
|---:|:-------------|---------:|-------------:|
|  0 | Alice        |    175.1 |           10 |
|  1 | Bobby        |    180.2 |           15 |
|  2 | Carl         |    190.3 |           20 |

convert pandas dataframe to markdown table

If you get an error when running the code sample, make sure you have the tabulate package installed.

shell

Copied!
pip install pandas tabulate

# or with pip3
pip3 install pandas tabulate

The DataFrame.to_markdown() method converts the DataFrame to a markdown object and returns the result as a string.

Notice that the output also contains the index column.

If you want to exclude the column, set the index argument to False when calling to_markdown().

main.py

Copied!
import pandas as pd

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = df.to_markdown(index=False)

print(markdown_table)

The code for this article is available on GitHub

Running the code sample produces the following output.

shell

Copied!
| first_name   |   salary |   experience |
|:-------------|---------:|-------------:|
| Alice        |    175.1 |           10 |
| Bobby        |    180.2 |           15 |
| Carl         |    190.3 |           20 |

exclude index column when converting to markdown table

If you use a Pandas version of less than 1.1, you would have to set the showindex argument to False instead of index.

main.py

Copied!
markdown_table = df.to_markdown(showindex=False)

You can print your pandas version with the pip show pandas command.

shell

Copied!
pip show pandas

pip3 show pandas

The pandas package uses the tabulate module under the hook, so you can pass tabulate parameters to the to_markdown() method.

main.py

Copied!
import pandas as pd

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = df.to_markdown(tablefmt='grid')

print(markdown_table)

The code for this article is available on GitHub

Running the code sample produces the following output.

shell

Copied!
+----+--------------+----------+--------------+
|    | first_name   |   salary |   experience |
+====+==============+==========+==============+
|  0 | Alice        |    175.1 |           10 |
+----+--------------+----------+--------------+
|  1 | Bobby        |    180.2 |           15 |
+----+--------------+----------+--------------+
|  2 | Carl         |    190.3 |           20 |
+----+--------------+----------+--------------+

converting dataframe to markdown table with tabulate parameters

# Converting the DataFrame to a Markdown table and writing the result to a file

You can use the with open() statement to write the markdown table to a file after the conversion.

main.py

Copied!
import pandas as pd

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = df.to_markdown(index=False)

file_path = 'example.md'

with open(file_path, 'w', encoding='utf-8') as md_file:
    md_file.write(markdown_table)

    print('Markdown table written to file.')

write converted markdown table to file

The code for this article is available on GitHub

The code sample produces the following example.md file in the same directory as the main.py script.

# Convert a Pandas DataFrame to a Markdown Table using `tabulate`

Alternatively, you can use the tabulate module directly.

First, make sure you have the module installed.

Open your terminal in your project's root directory and run the following command.

shell

Copied!
pip install pandas tabulate

# or with pip3
pip3 install pandas tabulate

Now import and use the module as follows.

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='pipe',
    headers='keys',
    showindex=False
)

print(markdown_table)

The code for this article is available on GitHub

Running the code sample produces the following output.

shell

Copied!
| first_name   |   salary |   experience |
|:-------------|---------:|-------------:|
| Alice        |    175.1 |           10 |
| Bobby        |    180.2 |           15 |
| Carl         |    190.3 |           20 |

convert pandas dataframe to markdown table using tabulate

You can pass different arguments to the tabulate method depending on how you want the markdown table to be formatted.

You can view all of the arguments the method takes on the package's GitHub page.

Here are some examples that you different formatting options.

The following code sample sets the tablefmt argument to "plain".

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='plain',
    headers='keys',
    showindex=False
)

print(markdown_table)

The code for this article is available on GitHub

The following output is produced.

shell

Copied!
first_name      salary    experience
Alice            175.1            10
Bobby            180.2            15
Carl             190.3            20

You can also set the tablefmt argument to "simple".

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='simple',
    headers='keys',
    showindex=False
)

# first_name      salary    experience
# ------------  --------  ------------
# Alice            175.1            10
# Bobby            180.2            15
# Carl             190.3            20
print(markdown_table)

The argument can also be set to "github" to use the GitHub markdown formatting style.

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='github',
    headers='keys',
    showindex=False
)

# | first_name   |   salary |   experience |
# |--------------|----------|--------------|
# | Alice        |    175.1 |           10 |
# | Bobby        |    180.2 |           15 |
# | Carl         |    190.3 |           20 |
print(markdown_table)

The other popular format is "grid".

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='grid',
    headers='keys',
    showindex=False
)

# +--------------+----------+--------------+
# | first_name   |   salary |   experience |
# +==============+==========+==============+
# | Alice        |    175.1 |           10 |
# +--------------+----------+--------------+
# | Bobby        |    180.2 |           15 |
# +--------------+----------+--------------+
# | Carl         |    190.3 |           20 |
# +--------------+----------+--------------+
print(markdown_table)

The code for this article is available on GitHub

There is also a "heavy_grid" option.

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='heavy_grid',
    headers='keys',
    showindex=False
)

# ┏━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
# ┃ first_name   ┃   salary ┃   experience ┃
# ┣━━━━━━━━━━━━━━╋━━━━━━━━━━╋━━━━━━━━━━━━━━┫
# ┃ Alice        ┃    175.1 ┃           10 ┃
# ┣━━━━━━━━━━━━━━╋━━━━━━━━━━╋━━━━━━━━━━━━━━┫
# ┃ Bobby        ┃    180.2 ┃           15 ┃
# ┣━━━━━━━━━━━━━━╋━━━━━━━━━━╋━━━━━━━━━━━━━━┫
# ┃ Carl         ┃    190.3 ┃           20 ┃
# ┗━━━━━━━━━━━━━━┻━━━━━━━━━━┻━━━━━━━━━━━━━━┛
print(markdown_table)

Or even "rounded_grid" to round the table's borders.

main.py

Copied!
import pandas as pd
from tabulate import tabulate

df = pd.DataFrame({
    'first_name': ['Alice', 'Bobby', 'Carl'],
    'salary': [175.1, 180.2, 190.3],
    'experience': [10, 15, 20]
})

markdown_table = tabulate(
    df,
    tablefmt='rounded_grid',
    headers='keys',
    showindex=False
)

# ╭──────────────┬──────────┬──────────────╮
# │ first_name   │   salary │   experience │
# ├──────────────┼──────────┼──────────────┤
# │ Alice        │    175.1 │           10 │
# ├──────────────┼──────────┼──────────────┤
# │ Bobby        │    180.2 │           15 │
# ├──────────────┼──────────┼──────────────┤
# │ Carl         │    190.3 │           20 │
# ╰──────────────┴──────────┴──────────────╯
print(markdown_table)

The code for this article is available on GitHub

You can view all of the other available grid formats in this section of the docs.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.

You can use the search field on my Home Page to filter through all of my articles.

How to convert a Pandas DataFrame to a Markdown Table

# Table of Contents