Skip to content

Repository files navigation

CrabXL for Python

A Rust-powered XLSX library with an openpyxl-compatible interface.

PyPI Python CI License

Rust engine · Status · Report an issue

About

CrabXL supports reading, creating, and editing XLSX files, including streaming read_only and write_only modes. Supported calls follow openpyxl conventions: use import crabxl as openpyxl to migrate compatible code. Processing runs in the shared Rust engine; openpyxl is not a runtime dependency.

The public openpyxl 3.1.5 API is supported and the unchanged openpyxl test suite passes for it. Before version 1.0, a minor version can change the API. Invalid input raises explicit errors. wb.save(path, calculate=True) also calculates formulas and saves their results, which openpyxl cannot do. See the migration guide and supported features.

Installation

pip install crabxl

Or with uv:

uv add crabxl

Wheels are available for CPython 3.11–3.15 on Linux x86_64/ARM64, Windows x86_64, and macOS Intel/Apple Silicon. Python 3.15 validation currently uses its release candidate. Source builds require Rust 1.99 or newer and Maturin.

Usage

Create and edit

from crabxl import Workbook, load_workbook

book = Workbook()
sheet = book.active
sheet["A1"] = "Hello"
sheet.append([1, 2, 3])
book.save("example.xlsx")
book.close()

book = load_workbook("example.xlsx")
try:
    book.active["A1"] = "Updated"
    book.save("updated.xlsx")
finally:
    book.close()

Streaming modes

from crabxl import Workbook, load_workbook

book = load_workbook("input.xlsx", read_only=True)
try:
    for row in book.active.iter_rows(values_only=True):
        print(row)
finally:
    book.close()

book = Workbook(write_only=True)
sheet = book.create_sheet("Values")
sheet.append([1, "hello", "=A1+1"])
book.save("output.xlsx")
book.close()

Read-only mode streams bounded batches. Write-only mode spools rows to disk and can be saved once; it does not support random cell access.

Memory and compression

All save modes accept compression_level: 0 stores without compression, 1–9 use Deflate, and the default is 6.

from crabxl import AutoMemory, ResourceOptions, SharedStringOptions, load_workbook

options = ResourceOptions(
    auto_memory=AutoMemory(maximum_bytes=64 * 1024**2),
    shared_strings=SharedStringOptions(storage="auto", cache_bytes=1024**2),
)
book = load_workbook("input.xlsx", resource_options=options)
try:
    book.active["A1"] = 42
    book.save("output.xlsx", compression_level=3)
finally:
    book.close()

Use max_memory_bytes for an explicit managed allowance, or AutoMemory to tune Auto selection. ResourceOptions also exposes input limits, SST RAM/disk strategies, cache and temporary-storage limits, and edit-overlay bounds. Ordinary loaded workbooks share one retained allowance across source catalogs, models, overlays and SST/cache; I/O working space remains additional. These settings do not cap process RSS. See memory limits.

Loading guards against ZIP bombs, deeply nested XML and huge XML tokens; the default opens every file Excel writes. Pass limits="strict" for uploads from strangers or limits="unlimited" for files you trust, or set the CRABXL_LIMITS environment variable.

Documentation

Contributing

Read CONTRIBUTING.md before you open a pull request. Report security problems as described in SECURITY.md.

License

Distributed under the MIT License. Third-party notices and test provenance are listed in third_party.

Releases

Used by

Contributors

Languages