Python Pandas Excel Export: Methods and Examples

How-to basics · Updated November 18, 2026

To export a pandas DataFrame to an Excel workbook, call DataFrame.to_excel(), for example df.to_excel("report.xlsx", index=False). For more control—such as choosing an Excel-writing engine, adding several sheets, or applying formatting—use pandas.ExcelWriter and pass it to to_excel().

How pandas Excel export works

Pandas turns tabular data in a DataFrame or Series into a worksheet inside an Excel file. It does not require Excel to be installed: pandas uses a Python library, called an engine, to create or update the workbook. The result is a file you can open in Excel, though some workbook features and data types do not translate exactly from Python.

The usual target is an .xlsx file. A DataFrame’s column labels become the worksheet’s header row by default, while its row index is also written unless you disable it. A Series can also be exported; pandas writes its values and, by default, its index. Exporting does not change the original DataFrame.

For a small, one-sheet report, the direct method is usually enough. Use an ExcelWriter when the job needs multiple sheets or when you want to make choices about the engine, file mode, or sheet behavior. Both approaches eventually write a workbook to a path or file-like object.

Start with a simple export

Install pandas and an Excel-writing engine if they are not already available. For example, install the openpyxl engine with pip install pandas openpyxl. Then create a DataFrame and write it to a file:

import pandas as pd

df = pd.DataFrame({
    "Product": ["Notebook", "Pen"],
    "Units": [12, 30],
    "Price": [4.5, 1.25],
})
df.to_excel("sales.xlsx", sheet_name="Sales", index=False)

This creates sales.xlsx in the current working directory, with a worksheet named Sales. Setting index=False omits the default row labels (0 and 1), which are often not useful in a report. If you leave it out, pandas writes those labels as an extra first column.

You can provide a full or relative path, such as "reports/sales.xlsx". The parent directory must already exist; pandas does not create missing folders for you. If the destination file already exists, a normal write replaces it. Check the path and file mode before exporting if the workbook contains material you need to keep.

Choose an engine and file format

The engine is the library that handles the Excel file. For common .xlsx exports, openpyxl and XlsxWriter are widely used. Pandas may select an available engine automatically, but naming one explicitly makes the dependency and behavior clearer. Install the chosen package in the same Python environment as pandas.

  • openpyxl: A common choice for reading and writing Excel workbooks. It can also be used to append to an existing workbook through pandas’ ExcelWriter.
  • XlsxWriter: A writing-focused engine with useful workbook-formatting features. It creates new workbooks; it is not a general tool for reading or editing an existing workbook.

To select an engine for a simple export, pass its name as an argument:

df.to_excel("sales.xlsx", index=False, engine="openpyxl")

Use .xlsx for a standard Excel workbook unless a particular workflow requires another format. Legacy .xls files have different engine and compatibility considerations, and support depends on the installed pandas version and libraries. An Excel export is not a CSV export: it can contain several sheets and workbook formatting, but it is also more complex and may use more memory.

Control the index, sheet name, and missing values

The to_excel() method includes useful options for shaping the exported worksheet. The most consequential choice for many reports is whether to include the index. Keep it when it represents meaningful row labels, such as dates or customer identifiers; omit it when it is merely the default sequence of row numbers.

  • sheet_name sets the worksheet name. Excel sheet names have restrictions, including a maximum of 31 characters and limits on certain characters.
  • index controls whether row labels are written; index=False is common for clean tables.
  • columns selects and orders columns to export, provided those columns exist in the DataFrame.
  • na_rep sets the text used for missing values, while inf_rep controls how infinity is represented.
  • header controls column labels, and startrow and startcol set the starting worksheet position.

For example, to export only two fields in a chosen order, use df.to_excel("summary.xlsx", columns=["Product", "Units"], index=False). Missing values are typically written as blank cells unless you specify a replacement string. Choose a replacement such as "Not available" only if users should see text in the cell; a blank may be more useful when they will filter or calculate from the worksheet.

Write multiple sheets in one workbook

Use one ExcelWriter context to write several DataFrames into a single workbook. Each call to to_excel() selects a sheet name. The context manager closes and saves the workbook when the block finishes, including when an error occurs during normal cleanup.

import pandas as pd

with pd.ExcelWriter("quarterly_report.xlsx", engine="openpyxl") as writer:
    sales.to_excel(writer, sheet_name="Sales", index=False)
    returns.to_excel(writer, sheet_name="Returns", index=False)
    summary.to_excel(writer, sheet_name="Summary", index=False)

Each sheet can have its own index, columns, and layout options. Sheet names must be distinct within the workbook. Prefer the context-manager pattern to creating a writer and forgetting to close it; an unclosed writer may leave the workbook incomplete or prevent it from being finalized properly.

If a report needs a title above the column headings, set startrow to leave space, then write the title separately with an engine-specific worksheet API. Keep track of the row positions when combining data from several tables. Pandas does not automatically design a dashboard or decide how related tables should be arranged.

Apply basic formatting and freeze panes

Pandas focuses on moving tabular data into a workbook, not reproducing every feature of an Excel-designed report. The freeze_panes option can keep headings visible while scrolling. For a single header row with no index column, df.to_excel("sales.xlsx", index=False, freeze_panes=(1, 0)) freezes the first row. The pair identifies the number of rows and columns to freeze.

For broader formatting, ExcelWriter exposes the workbook and worksheet objects provided by the selected engine. With XlsxWriter, for example, you can set column widths or add an autofilter after writing the DataFrame:

with pd.ExcelWriter("sales.xlsx", engine="xlsxwriter") as writer:
    df.to_excel(writer, sheet_name="Sales", index=False)
    worksheet = writer.sheets["Sales"]
    worksheet.set_column("A:A", 18)
    worksheet.autofilter(0, 0, len(df), len(df.columns) - 1)

This example assumes the DataFrame has at least one column. XlsxWriter’s row and column coordinates for the autofilter start at zero; the final row here includes the header. Formatting through an engine-specific API is useful for polished output, but it ties that part of the code to the chosen engine. Pandas’ Styler.to_excel() is another option for exporting supported table styles, although its styling capabilities are not a complete substitute for manually designing a workbook in Excel.

Append to or replace a sheet in an existing workbook

A normal export to a filename overwrites that file. To work with an existing workbook, use ExcelWriter with openpyxl and append mode. For example, mode="a" opens the existing file for adding sheets. The if_sheet_exists option determines what happens if the requested sheet name is already present.

with pd.ExcelWriter(
    "quarterly_report.xlsx",
    engine="openpyxl",
    mode="a",
    if_sheet_exists="replace",
) as writer:
    updated_summary.to_excel(writer, sheet_name="Summary", index=False)

Here, the existing Summary sheet is replaced, while other sheets are retained. This is different from replacing the whole workbook, but the old contents and layout of the replaced sheet are lost. The workbook must already exist for append mode. Check the pandas documentation for the exact options supported by your installed version; options include behaviors such as raising an error, replacing a sheet, or overlaying data.

Appending is not the same as merging new rows into a table. If you want to add records below existing worksheet data, you need to determine the correct starting row and write there; avoid assuming that pandas will detect the end of a formatted Excel table or preserve every workbook feature. Keep a backup when modifying a valuable file.

Check data types and Excel limits

Excel cells do not support every Python or pandas value in its original form. Dates and ordinary numeric values generally export naturally, but Excel has no native representation for every pandas dtype. In particular, timezone-aware datetimes need to be converted to a timezone-naive value or formatted as text before export. Decide whether to convert to a chosen timezone first; simply dropping timezone information can change what a timestamp means to a reader.

Missing values and infinity also deserve attention. Use na_rep or clean the DataFrame if blank cells would be ambiguous. If Excel users will calculate with exported values, avoid turning numbers into descriptive text unnecessarily. Check values with unusual precision, very long strings, or custom objects before writing, since Excel cell types and display rules differ from pandas’ in-memory representation.

A worksheet can contain at most 1,048,576 rows and 16,384 columns. Because a header uses one row, a DataFrame exported with headers can have no more than 1,048,575 data rows on a single sheet. A workbook can have multiple sheets, but that does not make a very large export automatically practical: pandas may need substantial memory to hold the data and produce the workbook. For large datasets, consider exporting partitions, writing a database extract, or using a columnar format such as Parquet instead.

Common export errors and how to fix them

An error saying that no usable Excel writer is available usually means the required engine package is missing from the active Python environment. Install openpyxl or XlsxWriter, then restart the process or notebook kernel if necessary. If the package is installed but the error remains, check which Python interpreter runs the script; environments and notebooks can use different interpreters.

A PermissionError can occur when the target workbook is open in Excel, locked by another process, or saved to a directory where the script cannot write. Close the workbook, choose a writable path, or save to a new filename. A missing-directory error means the parent folder does not exist; create it in Python before exporting.

Unexpected extra numbers in the first column usually come from the default index export. Add index=False if those row labels are not wanted. If a date, decimal, or blank looks wrong in Excel, inspect the underlying DataFrame value and Excel’s cell formatting separately: display formatting can make a valid stored value appear unexpected. Finally, do not assume that a successful export proves every workbook feature survived. Verify sheet names, representative values, and formatting in the generated file, especially after modifying an existing workbook.

Frequently Asked Questions

How do I export a pandas DataFrame to Excel without an index?

Call df.to_excel("output.xlsx", index=False). The column headings are still included by default; only the DataFrame’s row index is omitted.

How do I export multiple DataFrames to separate sheets?

Open one pd.ExcelWriter() context and call to_excel(writer, sheet_name=...) for each DataFrame. Use a different sheet name for each table, then let the context manager save the workbook.

Can pandas export to an Excel file that already exists?

Yes. With the openpyxl engine, use ExcelWriter with mode="a" to append to an existing workbook. Set if_sheet_exists deliberately if the target sheet may already exist; replacing a sheet removes its old contents.

Why does pandas say an Excel writer is not installed?

Pandas needs a compatible engine package to create the workbook. Install a package such as openpyxl or XlsxWriter in the same Python environment that runs your code, and specify engine="openpyxl" or engine="xlsxwriter" if you want to choose explicitly.

Does pandas export preserve Excel formatting?

A new export contains worksheet data and can include formatting added through pandas Styler or engine-specific APIs. A plain DataFrame export does not reproduce a carefully designed workbook, and modifying an existing file may not preserve every Excel feature. Inspect important output and keep a backup before overwriting or replacing sheets.

Choosing the right export approach

Use to_excel() directly for a straightforward, single-sheet file; use ExcelWriter for multiple sheets, engine-specific formatting, or controlled updates to an existing workbook. Decide whether the index belongs in the report, confirm that the data fits Excel’s worksheet limits, and select an engine your project can install and maintain. For a deliverable that people will review or edit in Excel, verify the saved workbook rather than relying only on the Python call completing successfully.

Related

Try it: the Date Difference Calculator: days, months, years and weekdays between two dates, with the DATEDIF formulas.

More in How-to basics

Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources

Spotted an error in this guide? Let us know.