Install & Compatibility
Where this runs
tested against v0.6.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.086s · 21.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.082s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
get_data
✓ from pyexcel_xlsx import get_data
For standalone usage of pyexcel-xlsx without the pyexcel unified API.
save_data
✓ from pyexcel_xlsx import save_data
For standalone usage of pyexcel-xlsx without the pyexcel unified API.
pyexcel
✓ import pyexcel as pe
✗ import pyexcel_xlsx
Since pyexcel version 0.2.2, pyexcel-xlsx is auto-loaded when pyexcel is installed. Explicit import of pyexcel_xlsx is not needed when using pyexcel's unified API (e.g., pe.get_sheet(), pe.save_as()).
This quickstart demonstrates how to write an `OrderedDict` to an XLSX file and then read it back using `pyexcel`'s unified API, which automatically utilizes `pyexcel-xlsx` for the XLSX format. It covers both saving and retrieving data from multi-sheet Excel files.
import pyexcel as pe
from collections import OrderedDict
import os
# Create some data for an Excel sheet
data = OrderedDict()
data.update({"Sheet 1": [[1, 2, 3], [4, 5, 6]]})
data.update({"Sheet 2": [["A", "B", "C"], [7, 8, 9]]})
file_name = "my_excel_file.xlsx"
# Save data to an XLSX file using pyexcel's unified API
pe.save_as(adict=data, dest_file_name=file_name)
print(f"Data successfully saved to {file_name}")
# Read data from the XLSX file
book = pe.get_book(file_name=file_name)
print(f"\nData read from {file_name}:")
for sheet_name in book.sheet_names():
sheet = book.sheet_by_name(sheet_name)
print(f"Sheet Name: {sheet_name}")
for row in sheet:
print(row)
# Clean up the created file
os.remove(file_name)
print(f"\nCleaned up {file_name}")
Debug
Known issues
breakingVersion 0.6.0 dropped support for Python versions lower than 3.6. Additionally, it introduced 'new style plugins' aligned with pyexcel-io v0.6.2+, which means older `pyexcel-io` plugins are incompatible with this version.fixEnsure your project uses Python 3.6 or newer. If upgrading from pre-0.6.0, review `pyexcel-io` documentation for changes to the plugin interface or upgrade all `pyexcel` related packages to their latest versions.
affects: 0.6.0 and higher
gotchaWhen using `pyexcel` as the main interface (e.g., `pyexcel.get_sheet()` or `pyexcel.save_as()`), `pyexcel-xlsx` is auto-loaded. Explicitly importing `pyexcel_xlsx` is generally not needed and can lead to confusion if standalone functions are used alongside the unified API.fixRely on `import pyexcel as pe` and use `pe.get_sheet()` or `pe.save_as()`. Only use `from pyexcel_xlsx import get_data, save_data` if you intend to use `pyexcel-xlsx` as a standalone library without `pyexcel`'s unified workflow.
affects: All versions since pyexcel 0.2.2
gotchaThe library primarily focuses on data processing. Features like fonts, colors, charts, or other styling elements within XLSX/XLSM files are not supported.fixIf advanced formatting or chart manipulation is required, consider using `openpyxl` directly or other specialized libraries.
affects: All versions
gotchapyexcel-xlsx does not support reading or writing password-protected XLSX/XLSM files.fixEnsure that any XLSX/XLSM files you intend to process with `pyexcel-xlsx` are not password-protected.
affects: All versions
gotchaThe `auto_detect_int` flag, commonly found in other Excel libraries, has no effect when using `pyexcel-xlsx`. This is because `openpyxl`, its underlying dependency, detects integers by default in Python 3.fixNo action required, as integer detection is handled automatically. If you encounter issues with integer detection, it's likely an `openpyxl` behavior rather than `pyexcel-xlsx`.
affects: All Python 3 compatible versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openpyxl'
The `pyexcel-xlsx` library is a wrapper for `openpyxl`, and `openpyxl` is a required peer dependency that must be installed separately.
fixInstall `openpyxl` using pip: `pip install openpyxl`
pyexcel_io.exceptions.SupportingPluginAvailableButNotInstalled: Please install one of these plugins for read data in 'xlsx': pyexcel-xls,pyexcel-xlsx.
The core `pyexcel` library is installed, but the specific plugin (`pyexcel-xlsx`) required to handle XLSX file formats is missing.
fixInstall the `pyexcel-xlsx` plugin using pip: `pip install pyexcel-xlsx`
OSError: Unsupported file type
This error occurs when `pyexcel` cannot find a suitable plugin to handle the specified file type (e.g., '.xlsx') or if the file itself is corrupted or not a valid Excel file.
fixEnsure `pyexcel-xlsx` is installed (`pip install pyexcel-xlsx`). If the file is an old '.xls' format, ensure `pyexcel-xls` is also installed. If it's a renamed file (e.g., an '.xls' file renamed to '.xlsx'), convert it to a genuine '.xlsx' format using Excel's 'Save As' function, or use `pyexcel.save_book_as` to convert it programmatically.
Writing to Excel files with PyExcel not working on PyInstaller bundled exe (Windows), writes empty-corrupt files
When bundling applications with PyInstaller, `pyexcel-xlsx` plugins might not be automatically detected, leading to corrupted output files without explicit errors.
fixExplicitly import `pyexcel-xlsx` in your main script, or add `hiddenimports=['pyexcel_xlsx']` to your PyInstaller spec file to ensure the plugin is included in the executable.
Upgrade
Version history
0.6.1latest on PyPI · released Mar 5, 2025
Audit
Dependencies
pyexcelrequiredCore framework that pyexcel-xlsx extends as a plugin for unified Excel operations.
pyexcel-iorequiredBase library providing the plugin interface and I/O operations for pyexcel. Required version >= 0.6.2 for compatibility with new style plugins.
openpyxlrequiredUnderlying library used by pyexcel-xlsx to handle XLSX/XLSM file formats.