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 |

note

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 |
+------------+---------------+---------+

note

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 |
  +------------+---------------+---------+

note

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 the tabulate library first.
  • Use index=False to exclude the DataFrame index.
  • Pass tabulate arguments like tablefmt='grid' to customize the output style.
• 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.