Install & Compatibility
Where this runs
tested against v0.8.2 · 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.000s · 20.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CalamineWorkbook
✓ from python_calamine import CalamineWorkbook
Primary class for interacting with workbooks.
This quickstart demonstrates how to open an Excel file using `CalamineWorkbook.from_path`, retrieve sheet names, and extract data into a Python list of lists. By default, `python-calamine` skips empty rows and columns, but this behavior can be altered using `skip_empty_area=False` when calling `to_python()` on a sheet. For `pandas` users, versions 2.2 and above have built-in support for the 'calamine' engine in `read_excel`.
import os
from python_calamine import CalamineWorkbook
# Create a dummy Excel file for demonstration
# In a real scenario, 'file.xlsx' would already exist.
# For this quickstart, we'll simulate reading a file.
# You would replace 'file.xlsx' with your actual file path.
# Placeholder for creating a file, as we cannot write to disk directly in this environment.
# Assume 'dummy_file.xlsx' exists with at least one sheet named 'Sheet1'
# and some data like [['1', '2', '3'], ['4', '5', '6']].
try:
# Attempt to open a non-existent file to demonstrate error handling
# In a real application, ensure the file exists.
workbook = CalamineWorkbook.from_path('dummy_file.xlsx')
print(f"Sheet names: {workbook.sheet_names}")
# Get data from the first sheet
if workbook.sheet_names:
sheet_data = workbook.get_sheet_by_name(workbook.sheet_names[0]).to_python()
print(f"Data from '{workbook.sheet_names[0]}': {sheet_data}")
# Example with skipping empty areas (default is True)
# To suppress this, set skip_empty_area=False
# sheet_data_with_empty = workbook.get_sheet_by_name(workbook.sheet_names[0]).to_python(skip_empty_area=False)
# print(f"Data (including empty): {sheet_data_with_empty}")
except FileNotFoundError:
print("Please ensure 'dummy_file.xlsx' exists in the current directory or provide a valid path.")
print("For example, create a simple Excel file with content and try again.")
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaCalamine does not perform implicit data type conversions for numbers and may change strings into numbers, which can lead to unexpected data types if not handled explicitly. Excel numbers are read as floats.fixBe mindful of data types when reading. If using with Pandas, explicitly define dtypes if possible, or perform post-processing to cast to desired types. Calamine's philosophy prioritizes speed by avoiding these conversions.
affects: All versions
gotchaBy default, `python-calamine` skips empty rows/columns before the actual data area. This might lead to unexpected results if leading empty cells are significant.fixTo include empty areas, use `workbook.get_sheet_by_name('Sheet1').to_python(skip_empty_area=False)`. affects: All versions
gotchaSome users reported performance degradation when reading data over VPN network connections starting from version 0.2.3.fixIf experiencing slow reads over VPN, consider testing with local files or older versions (if compatible with your needs) to isolate the issue. Report specific performance issues with clear reproduction steps on the GitHub repository.
affects: 0.2.3 and later
gotchaIssues have been reported where the first two columns in old `.xls` files are read incorrectly.fixIf working with old `.xls` files and encountering malformed data, verify the first two columns. Consider converting problematic `.xls` files to `.xlsx` format if possible, or using a different library for `.xls` files if `python-calamine` exhibits consistent errors.
affects: All versions, specifically impacting legacy .xls files
deprecatedFor `pandas` versions 2.0 and 2.1, using `python-calamine` as an engine for `read_excel` required a monkeypatch.fixUpgrade to `pandas` 2.2 or higher for built-in support, which automatically registers `python-calamine` as a `read_excel` engine.
affects: pandas 2.0, 2.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'calamine'
The python-calamine package is not installed or not available in the current Python environment.
fixpip install python-calamine
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/your_file.xlsx'
The specified file path does not exist, or the Python process lacks the necessary permissions to access the file or its directory.
fixVerify the file path is correct, including the file name and extension, and ensure the file exists at that location and is accessible.
ValueError: Invalid file format
The file provided to `calamine.read_workbook()` is not a valid Excel (.xlsx, .xls, .xlsb) or ODF (.ods) spreadsheet, or the file is corrupted.
fixEnsure the input file is a valid, uncorrupted spreadsheet in a supported format.
AttributeError: 'CalamineWorkbook' object has no attribute 'sheets'
The `CalamineWorkbook` object does not have a direct `sheets` attribute; sheet names are accessed via the `sheet_names` property, and individual sheets via `get_sheet_by_name` or `get_sheet_by_index`.
fixUse `workbook.sheet_names` to get a list of sheet names, or `workbook.get_sheet_by_name("Sheet1")` to retrieve a specific sheet object. ImportError: cannot import name 'Workbook' from 'calamine'
The `calamine` module does not expose a class named `Workbook`; the main class for a workbook object is `CalamineWorkbook`, or you might be looking for the `read_workbook` function.
fixImport `CalamineWorkbook` or `read_workbook` explicitly, e.g., `from calamine import CalamineWorkbook` or `from calamine import read_workbook`.
Upgrade
Version history
0.8.2latest on PyPI · released Jul 13, 2026
Audit
Dependencies
calamine (Rust library)requiredCore parsing engine (Rust dependency)
pyo3requiredRust/Python bindings framework
maturinrequiredBuild tool for Rust/Python projects
pandas (>=2.2)optionalBuilt-in support for 'calamine' engine in `read_excel`. Optional if not using pandas.