How to Convert Pandas DataFrame to Markdown Tables?

Imagine you’ve spent hours analyzing data in Python using Pandas, and now you need to share your findings in a report. That’s where Markdown tables come in. They’re simple, lightweight, and perfect for displaying data on platforms like GitHub and Jupyter Notebooks in a clear, easy-to-read format. In this article, we’ll explore different methods to convert a Pandas DataFrame to Markdown tables so that you can present your data in a well-organized and professional manner.

Why Convert a Pandas DataFrame to Markdown Tables?

Converting DataFrames into Markdown tables makes it easy to share data. Here are some situations where this conversion becomes really useful:

1. Blogging & Article Writing: If you write content in the field of Data Science, Markdown tables allow you to embed DataFrames in your blog posts on various platforms, such as Medium or Dev.to, without losing their format.
2. Technical Documentation: Technical writers often include structured data in API documentation, research papers, or tutorials. By using Markdown tables, they can present the information clearly and organized.
3. README Files & Open Source Projects: For developers, Markdown tables are a handy tool in README files. They make it easier for contributors to understand key project details, and they look great on GitHub too.
4. Forums & Messaging Platforms: If you’re active on platforms like Stack Overflow, Slack, or Discord, you’ve probably seen Markdown tables used to display data. It’s a simple, effective way to keep discussions organized and readable.
5. Research Papers: In academic writing, Markdown tables help researchers present their findings concisely, which makes analysis easier for the reader.
6. Data Visualizations: Sometimes, a chart or graph isn’t needed. In those cases, Markdown tables are a straightforward way to present data without overwhelming your audience.
7. Project Reports: For project managers, Markdown tables are the perfect tool for structuring reports. Stakeholders can quickly visualize key data without needing to rely on complex software.

Simple Methods for Converting a Pandas DataFrame to Markdown Tables

The methods discussed below require the tabulate library in order to convert your DataFrame into a Markdown table. To install this library, run the following pip command:

pip install tabulate

If needed, you can also install a specific version of a package based on your project requirements.

1. Using Pandas to_markdown()

This is the simplest method to convert a Pandas DataFrame to Markdown, especially if you’re using Pandas version 1.0 or later since it provides a built-in method called to_markdown().

Example Code

• First, we import pandas and create a dictionary called data which is then converted into a simple DataFrame using pd.DataFrame.
• Next, we use the to_markdown() function to convert the DataFrame to a Markdown-formatted table.
• The index=False argument removes the index column from the table for a cleaner look.
• Finally, we print the resulting Markdown table.

import pandas as pd

# Sample DataFrame
data = {
    'Name': ['Peter', 'Henry', 'Lisa'],
    'Age': [24, 30, 35],
    'Country': ['England', 'Germany', 'Finland']
}
df = pd.DataFrame(data)

# Convert to Markdown
markdown_table = df.to_markdown(index=False)
print(markdown_table)

Output

2. Using tabulate Library

While Pandas to_markdown() is simple, the tabulate library offers more control over the table’s appearance. It’s a great choice when you need additional formatting options, such as adjusting column alignment, adding custom headers, or selecting different Markdown styles.

Example Code

• Here, we import tabulate along with pandas and create our DataFrame.
• The tabulate() function converts the DataFrame into a Markdown table with a specified format using tablefmt=github.
• headers='keys' uses the DataFrame columns as headers.
• showindex=False removes the index from the table as before.
• Finally, we print our Markdown Table to the output screen.

import pandas as pd
from tabulate import tabulate

# Sample DataFrame
data = {
    'Employee': ['Dan', 'John', 'Emma', 'Mark'],
    'Department': ['Sales', 'Finance', 'HR', 'Marketing'],
    'Salary': [60000, 75000, 72000, 68000]
}
df = pd.DataFrame(data)

# Convert to Markdown with tabulate
markdown_table = tabulate(df, headers='keys', tablefmt='github', showindex=False)
print(markdown_table)

Output

Saving a DataFrame as a Markdown File

After converting your Pandas DataFrame to a Markdown table, you may need to save it as a Markdown file. You can simply use Python’s file handling to accomplish this.

Example Code

• The open() function creates a file named table.md in write mode w.
• The with statement ensures that the file is properly closed once writing is complete.
• The f.write(markdown_table) command writes the pre-converted Markdown table to the file.
• Finally, print("Done!") confirms that the file has been written successfully.

markdown_table = df.to_markdown()  # Convert DataFrame to Markdown

with open("table.md", "w") as f:
    f.write(markdown_table)  # Write the Markdown string to the file

print("Done!") #Indicate Completion

Output

You can open the .md file using your browser or any editor.

Conclusion

In this article, we explored two methods to convert a Pandas DataFrame to Markdown tables: using Pandas’ built-in to_markdown() function for a quick conversion and the tabulate library for more control over table formatting. We also covered how to write your Pandas DataFrame to a Markdown file, making it easy to share with others.

So the next time you need to share your data, remember that Markdown tables can be your best friend—lightweight, readable, and simple. Depending on your needs, you can choose the method that works best for you.

For more beginner-friendly Python tutorials, don’t forget to explore our Python Series at Syntax Scenarios!

Related Resources