Python Pandas: How to Convert DataFrame to Markdown Table (to_markdown
, tabulate
)
Converting a Pandas DataFrame into a Markdown table is extremely useful for documentation, reports, sharing data in text-based formats (like GitHub issues or README files), or for display in environments that render Markdown. Pandas provides a built-in to_markdown()
method, which internally uses the powerful tabulate
library, offering various formatting options.
This guide explains how to use DataFrame.to_markdown()
and the tabulate
library directly to generate Markdown tables from your Pandas DataFrames.
Why Convert DataFrame to Markdown?
- Documentation: Embedding tabular data directly into Markdown files (like README.md, wikis, or technical documentation).
- Reporting: Creating human-readable text-based reports.
- Sharing: Easily sharing small tables in emails, forums, or chat messages that support Markdown.
- Version Control: Storing simple tabular data in a plain text format that's friendly to version control systems like Git.
- Static Site Generators: Many static site generators use Markdown as their primary content format.
Prerequisites: Installing tabulate
The DataFrame.to_markdown()
method in Pandas relies on the tabulate
library being installed. If you don't have it, install both Pandas and tabulate
:
pip install pandas tabulate
# Or if using pip3:
pip3 install pandas tabulate
Example DataFrame:
import pandas as pd
data = {
'PlayerID': [101, 102, 103, 104],
'Player Name': ['Alice', 'Bob', 'Charlie', 'Diana'],
'Team': ['Dragons', 'Wizards', 'Dragons', 'Knights'],
'Score': [1500, 1750, 1400, 1820],
'Rank': [3, 1, 4, 2]
}
df = pd.DataFrame(data)
print("Original DataFrame:")
print(df)
Output:
Original DataFrame:
PlayerID Player Name Team Score Rank
0 101 Alice Dragons 1500 3
1 102 Bob Wizards 1750 1
2 103 Charlie Dragons 1400 4
3 104 Diana Knights 1820 2
Method 1: Using DataFrame.to_markdown()
(Recommended Pandas Way)
This method is available directly on DataFrame objects.
Basic Conversion
By default, to_markdown()
includes the DataFrame's index and uses a standard Markdown table format (often GitHub Flavored Markdown).
import pandas as pd
df_example = pd.DataFrame({
'PlayerID': [101, 102], 'Player Name': ['Alice', 'Bob'], 'Score': [1500, 1750]
})
markdown_string_with_index = df_example.to_markdown()
print("Markdown table (with index, default format):")
print(markdown_string_with_index)
Output (will vary slightly based on tabulate version, typically GitHub style):
Markdown table (with index, default format):
| | PlayerID | Player Name | Score |
|---:|-----------:|:--------------|--------:|
| 0 | 101 | Alice | 1500 |
| 1 | 102 | Bob | 1750 |
Excluding the Index (index=False
)
To omit the DataFrame's index from the Markdown output, set index=False
.
import pandas as pd
df_example = pd.DataFrame({
'PlayerID': [101, 102], 'Player Name': ['Alice', 'Bob'], 'Score': [1500, 1750]
})
markdown_string_no_index = df_example.to_markdown(index=False)
print("Markdown table (without index):")
print(markdown_string_no_index)
Output:
Markdown table (without index)
| PlayerID | Player Name | Score |
|-----------:|:--------------|--------:|
| 101 | Alice | 1500 |
| 102 | Bob | 1750 |
In Pandas versions prior to 1.1, the parameter was showindex=False
instead of index=False
.
Using tabulate
Parameters (e.g., tablefmt
)
Since to_markdown()
uses tabulate
internally, you can pass most tabulate
parameters directly to to_markdown()
. The tablefmt
parameter is particularly useful for changing the table style.
import pandas as pd
df_example = pd.DataFrame({
'PlayerID': [101, 102], 'Player Name': ['Alice', 'Bob'], 'Score': [1500, 1750]
})
# Using 'grid' format from tabulate
markdown_grid_format = df_example.to_markdown(index=False, tablefmt='grid')
print("Markdown table (grid format, no index):")
print(markdown_grid_format)
Output:
Markdown table (grid format, no index):
+------------+---------------+---------+
| PlayerID | Player Name | Score |
+============+===============+=========+
| 101 | Alice | 1500 |
+------------+---------------+---------+
| 102 | Bob | 1750 |
+------------+---------------+---------+
Refer to the tabulate
library's documentation for a full list of tablefmt
options (e.g., 'pipe'
, 'simple'
, 'html'
, 'latex'
, 'rst'
, etc.).
Method 2: Using the tabulate
Library Directly
You can also use the tabulate
library directly by passing your DataFrame to its tabulate()
function. This offers the same level of control over formatting.
import pandas as pd
from tabulate import tabulate # Import the function
df_example = pd.DataFrame({
'PlayerID': [101, 102, 103],
'Player Name': ['Alice', 'Bob', 'Charlie'],
'Score': [1500, 1750, 1400]
})
# ✅ Basic usage with tabulate
# headers='keys' uses DataFrame column names as headers
# showindex=False (or "False") omits the index
markdown_tabulate_direct = tabulate(
df_example,
headers='keys',
tablefmt='pipe', # Default for df.to_markdown() is often 'github' or 'pipe'
showindex=False
)
print("Markdown table (using tabulate directly, pipe format):")
print(markdown_tabulate_direct)
Output:
Markdown table (using tabulate directly, pipe format):
| PlayerID | Player Name | Score |
|-----------:|:--------------|--------:|
| 101 | Alice | 1500 |
| 102 | Bob | 1750 |
| 103 | Charlie | 1400 |
Exploring Different Table Formats (tablefmt
)
The tabulate
library offers a wide variety of table formats via the tablefmt
argument. Here are a few examples:
-
plain
:import pandas as pd
from tabulate import tabulate
df_example = pd.DataFrame({
'PlayerID': [101, 102, 103],
'Player Name': ['Alice', 'Bob', 'Charlie'],
'Score': [1500, 1750, 1400]
})
md_plain = tabulate(df_example, headers='keys', tablefmt='plain', showindex=False)
print("Tabulate format 'plain':\n" + md_plain)Output:
Tabulate format 'plain':
PlayerID Player Name Score
101 Alice 1500
102 Bob 1750
103 Charlie 1400 -
simple
:import pandas as pd
from tabulate import tabulate
df_example = pd.DataFrame({
'PlayerID': [101, 102, 103],
'Player Name': ['Alice', 'Bob', 'Charlie'],
'Score': [1500, 1750, 1400]
})
md_simple = tabulate(df_example, headers='keys', tablefmt='simple', showindex=False)
print("Tabulate format 'simple':\n" + md_simple)Output:
Tabulate format 'simple':
PlayerID Player Name Score
---------- ------------- -------
101 Alice 1500
102 Bob 1750
103 Charlie 1400 -
github
(Commonly used for GitHub Markdown):import pandas as pd
from tabulate import tabulate
df_example = pd.DataFrame({
'PlayerID': [101, 102, 103],
'Player Name': ['Alice', 'Bob', 'Charlie'],
'Score': [1500, 1750, 1400]
})
md_github = tabulate(df_example, headers='keys', tablefmt='github', showindex=False)
print("Tabulate format 'github':\n" + md_github)Output:
Tabulate format 'github':
| PlayerID | Player Name | Score |
|------------|---------------|---------|
| 101 | Alice | 1500 |
| 102 | Bob | 1750 |
| 103 | Charlie | 1400 | -
grid
:import pandas as pd
from tabulate import tabulate
df_example = pd.DataFrame({
'PlayerID': [101, 102, 103],
'Player Name': ['Alice', 'Bob', 'Charlie'],
'Score': [1500, 1750, 1400]
})
md_grid = tabulate(df_example, headers='keys', tablefmt='grid', showindex=False)
print("Tabulate format 'grid':\n" + md_grid)Output:
Tabulate format 'grid':
+------------+---------------+---------+
| PlayerID | Player Name | Score |
+============+===============+=========+
| 101 | Alice | 1500 |
+------------+---------------+---------+
| 102 | Bob | 1750 |
+------------+---------------+---------+
| 103 | Charlie | 1400 |
+------------+---------------+---------+
Explore the tabulate
documentation for more tablefmt
options like heavy_grid
, rounded_grid
, rst
, html
, etc.
Writing Markdown Table to a File
Once you have the Markdown string, you can easily write it to a .md
file.
The following example will create a dataframe_output.md
file in your current directory containing the grid-formatted Markdown table.
import pandas as pd
df_example = pd.DataFrame({
'PlayerID': [101, 102], 'Player Name': ['Alice', 'Bob'], 'Score': [1500, 1750]
})
markdown_output = df_example.to_markdown(index=False, tablefmt='grid')
file_path = 'dataframe_output.md'
try:
with open(file_path, 'w', encoding='utf-8') as f:
f.write(markdown_output)
print(f"Markdown table successfully written to '{file_path}'")
except IOError as e:
print(f"Error writing to file: {e}")
Conclusion
Converting a Pandas DataFrame to a Markdown table is essential for integrating tabular data into text-based documents and platforms.
- The
DataFrame.to_markdown()
method is the most convenient built-in Pandas way. Remember to install thetabulate
library first.- Use
index=False
to exclude the DataFrame index. - Pass
tabulate
arguments liketablefmt='grid'
to customize the output style.
- Use
- Using the
tabulate
library directly (from tabulate import tabulate; tabulate(df, ...
) offers the same rich formatting capabilities and is useful if you're working with data structures other than Pandas DataFrames as well.
Both methods provide flexible options to generate well-formatted Markdown tables from your DataFrame data, ready for documentation, reporting, or sharing.