Install & Compatibility
Where this runs
tested against v0.8.6 · 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.108s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.094s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Xlsx2csv
✓ from xlsx2csv import Xlsx2csv
This quickstart demonstrates how to convert an XLSX file to CSV using the `Xlsx2csv` class with a context manager for proper resource cleanup. It also includes basic error handling and cleanup of the dummy files for a self-contained example.
import os
from xlsx2csv import Xlsx2csv
# Create a dummy XLSX file for demonstration
# In a real scenario, this file would already exist.
# For simplicity, we'll just demonstrate the conversion logic.
# You might use openpyxl to create a real .xlsx file for testing:
# import openpyxl
# wb = openpyxl.Workbook()
# ws = wb.active
# ws['A1'] = 'Header1'
# ws['B1'] = 'Header2'
# ws['A2'] = 'Data1'
# ws['B2'] = 'Data2'
# wb.save('example.xlsx')
# Ensure a dummy file path exists for the example
excel_file = 'example.xlsx'
csv_output = 'example.csv'
# To make this runnable without needing openpyxl just for quickstart:
# Create a dummy excel_file (normally this would be a real .xlsx)
with open(excel_file, 'w') as f:
f.write('This is a placeholder for a .xlsx file content.')
# Recommended: using context manager for proper resource cleanup
try:
with Xlsx2csv(excel_file, outputencoding="utf-8") as converter:
converter.convert(csv_output)
print(f"Successfully converted '{excel_file}' to '{csv_output}'.")
# Optionally, read and print the CSV content to verify
if os.path.exists(csv_output):
with open(csv_output, 'r', encoding='utf-8') as f_csv:
print("CSV Content:\n" + f_csv.read())
else:
print(f"Error: CSV file '{csv_output}' not created.")
except Exception as e:
print(f"An error occurred during conversion: {e}")
finally:
# Clean up dummy files
if os.path.exists(excel_file):
os.remove(excel_file)
if os.path.exists(csv_output):
os.remove(csv_output)
xlsx2csv --version
Debug
Known issues
breakingPrior to version 0.8.2, `xlsx2csv` might have used or re-raised `zipfile.BadZipfile`. With the update in version 0.8.2, `BadZipFile` (with a capital 'F') is used, aligning with deprecations in Python's `zipfile` module since Python 3.2.fixUpdate any error handling catching `zipfile.BadZipfile` to `zipfile.BadZipFile`.
affects: <0.8.2
breakingVersions of `xlsx2csv` prior to 0.8.3 could encounter a `SyntaxError` when run on Python 3.12 or newer due to changes in how Python 3.12 handles invalid escape sequences in regular expressions.fixUpgrade to `xlsx2csv` version 0.8.3 or newer to ensure compatibility with Python 3.12+.
affects: <0.8.3
gotchaNot using `Xlsx2csv` within a `with` statement (context manager) may lead to `ResourceWarning` in modern Python versions due to improper resource cleanup.fixAlways use `Xlsx2csv` with a `with` statement: `with Xlsx2csv('file.xlsx') as converter: converter.convert('file.csv')`. affects: All versions (if not using context manager)
gotchaIn versions prior to 0.8.3, a bug existed when processing XLSX files with missing workbook relationships, which could lead to conversion failures or unexpected behavior.fixUpgrade to `xlsx2csv` version 0.8.3 or newer to resolve issues related to missing workbook relationships.
affects: <0.8.3
gotchaXLSX files containing hyperlinks could cause crashes or incorrect processing in `xlsx2csv` versions older than 0.8.2.fixUpgrade to `xlsx2csv` version 0.8.2 or newer to correctly handle XLSX files with hyperlinks.
affects: <0.8.2
Errors
Common errors & fixes
xlsx2csv: command not found
The `xlsx2csv` command-line tool's executable is not in your system's PATH, or the package was not installed with its command-line script accessible.
fixEnsure `xlsx2csv` is installed in a directory that is in your system's PATH, or run it using Python's module execution: `python -m xlsx2csv input.xlsx output.csv`
ModuleNotFoundError: No module named 'xlsx2csv'
The `xlsx2csv` Python package is not installed in the Python environment where your script is being executed.
fixInstall the package using pip: `pip install xlsx2csv`
FileNotFoundError: [Errno 2] No such file or directory: 'your_input_file.xlsx'
The specified input XLSX file does not exist at the provided path, or the file name is incorrect.
fixVerify the file path and name are correct, and ensure the file exists at that location. Use an absolute path if you are unsure of the current working directory.
PermissionError: [Errno 13] Permission denied: 'your_output_file.csv'
The program does not have the necessary write permissions for the directory where it's attempting to create the output CSV file.
fixChange the output directory to one where you have write permissions, or ensure the current working directory has appropriate permissions.
ImportError: cannot import name 'convert' from 'xlsx2csv'
The `xlsx2csv` library does not expose a top-level function named 'convert'. Its primary Python API is through the `Xlsx2csv` class.
fixTo use the Python API, import and instantiate the `Xlsx2csv` class: `from xlsx2csv import Xlsx2csv` then `Xlsx2csv('input.xlsx', outputfile=open('output.csv', 'w')).convert()` Upgrade
Version history
0.8.6latest on PyPI · released Jan 31, 2026
Audit
Dependencies
No dependency data recorded yet.