{"id":2730,"library":"python-calamine","title":"python-calamine","description":"python-calamine is a Python binding for the Rust library 'calamine', designed for fast reading of Excel (.xlsx, .xls, .xlsb) and ODF (.ods) spreadsheet files. It is actively maintained, with version 0.6.2 released in February 2026, indicating a regular release cadence.","status":"active","version":"0.6.2","language":"en","source_language":"en","source_url":"https://github.com/dimastbk/python-calamine","tags":["python","excel","ods","xlsx","spreadsheet","rust","performance","data processing","open-document"],"install":[{"cmd":"pip install python-calamine","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge python-calamine","lang":"bash","label":"Conda-forge"}],"dependencies":[{"reason":"Core parsing engine (Rust dependency)","package":"calamine (Rust library)","optional":false},{"reason":"Rust/Python bindings framework","package":"pyo3","optional":false},{"reason":"Build tool for Rust/Python projects","package":"maturin","optional":false},{"reason":"Built-in support for 'calamine' engine in `read_excel`. Optional if not using pandas.","package":"pandas (>=2.2)","optional":true}],"imports":[{"note":"Primary class for interacting with workbooks.","symbol":"CalamineWorkbook","correct":"from python_calamine import CalamineWorkbook"}],"quickstart":{"code":"import os\nfrom python_calamine import CalamineWorkbook\n\n# Create a dummy Excel file for demonstration\n# In a real scenario, 'file.xlsx' would already exist.\n# For this quickstart, we'll simulate reading a file.\n# You would replace 'file.xlsx' with your actual file path.\n\n# Placeholder for creating a file, as we cannot write to disk directly in this environment.\n# Assume 'dummy_file.xlsx' exists with at least one sheet named 'Sheet1'\n# and some data like [['1', '2', '3'], ['4', '5', '6']].\n\ntry:\n    # Attempt to open a non-existent file to demonstrate error handling\n    # In a real application, ensure the file exists.\n    workbook = CalamineWorkbook.from_path('dummy_file.xlsx')\n    print(f\"Sheet names: {workbook.sheet_names}\")\n    \n    # Get data from the first sheet\n    if workbook.sheet_names:\n        sheet_data = workbook.get_sheet_by_name(workbook.sheet_names[0]).to_python()\n        print(f\"Data from '{workbook.sheet_names[0]}': {sheet_data}\")\n    \n    # Example with skipping empty areas (default is True)\n    # To suppress this, set skip_empty_area=False\n    # sheet_data_with_empty = workbook.get_sheet_by_name(workbook.sheet_names[0]).to_python(skip_empty_area=False)\n    # print(f\"Data (including empty): {sheet_data_with_empty}\")\n\nexcept FileNotFoundError:\n    print(\"Please ensure 'dummy_file.xlsx' exists in the current directory or provide a valid path.\")\n    print(\"For example, create a simple Excel file with content and try again.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Be 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.","message":"Calamine 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To include empty areas, use `workbook.get_sheet_by_name('Sheet1').to_python(skip_empty_area=False)`.","message":"By default, `python-calamine` skips empty rows/columns before the actual data area. This might lead to unexpected results if leading empty cells are significant.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"Some users reported performance degradation when reading data over VPN network connections starting from version 0.2.3.","severity":"gotcha","affected_versions":"0.2.3 and later"},{"fix":"If 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.","message":"Issues have been reported where the first two columns in old `.xls` files are read incorrectly.","severity":"gotcha","affected_versions":"All versions, specifically impacting legacy .xls files"},{"fix":"Upgrade to `pandas` 2.2 or higher for built-in support, which automatically registers `python-calamine` as a `read_excel` engine.","message":"For `pandas` versions 2.0 and 2.1, using `python-calamine` as an engine for `read_excel` required a monkeypatch.","severity":"deprecated","affected_versions":"pandas 2.0, 2.1"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}