oxlsx

A high-performance Rust library for reading and writing .xlsx files with full formatting support — designed as an openpyxl equivalent in Rust, with Python bindings (PyO3).

5–10x faster than openpyxl on write operations. Streaming reads via open_readonly().

Status

v0.2.0 — phases 1–14 plus temporal values, style API additions, and Python type stubs. See PyPI and crates.io for published packages.

openpyxl-migration additions (v0.1.1): conditional formatting (FormulaRule / CellIsRule), sheet auto_filter, PatternFill, get_column_letter / column_index_from_string, and dataframe_to_rows.

New in v0.2.0

• Typed datetime, time, and duration values, including Python datetime, time, and timedelta support.
• Strikethrough fonts, theme-color tint preservation, fill-color aliases, and cell row/column accessors.
• Python type stubs for editor autocomplete and static analysis.
• Atomic workbook saves with symbolic-link destination rejection.

Rust migration from v0.1.1: this release includes source-breaking API changes:

• Replace Color::Theme(index) with Color::Theme(index, None) (or Some(tint)); update matching patterns to accept the second field.
• Include the new Font.strike field in complete struct literals, or use ..Default::default().
• Handle Value::DateTime, Value::Time, and Value::Duration in exhaustive matches.

The pandas engine remains planned; pandas Styler support is not included.

Install

Rust

# Cargo.toml
[dependencies]
oxlsx = "0.2.0"

Or pin to a tag from git: oxlsx = { git = "https://github.com/alvaroroco/oxlsx", tag = "v0.2.0" }

Python (build from source via maturin)

Prebuilt abi3 wheels (a single cp38-abi3 wheel per platform, runs on CPython 3.8+) are published to PyPI on each release:

pip install oxlsx

To build from source, use maturin. The wheel build (abi3 extension-module) is configured in pyproject.toml, so no extra flags are needed:

pip install maturin
maturin develop --release   # install into the active venv
# or: maturin build --release  -> target/wheels/oxlsx-0.2.0-cp38-abi3-*.whl

Contributors running the in-crate PyO3 tests use the interpreter-linked path instead: cargo test --features python.

Usage

Reading

use oxlsx::{Workbook, Value};

fn main() -> Result<(), oxlsx::OxlsxError> {
    let wb = Workbook::open("file.xlsx")?;

    // Access by index or name
    let ws = wb.sheet(0).unwrap();
    let ws = wb.sheet_by_name("Employees").unwrap();

    println!("Sheets: {:?}", wb.sheetnames());
    println!("Active: {}", wb.active().unwrap().title());

    if let Some(cell) = ws.cell("A1") {
        match cell.value() {
            Value::String(s)  => println!("text: {s}"),
            Value::Number(n)  => println!("number: {n}"),
            Value::Bool(b)    => println!("bool: {b}"),
            Value::Date(d)    => println!("date: {d}"),
            Value::DateTime(d) => println!("datetime: {d}"),
            Value::Time(t)    => println!("time: {t}"),
            Value::Duration(d) => println!("duration: {d}"),
            Value::Formula(f) => println!("formula: {f}"),
            Value::Empty      => println!("empty"),
        }

        if let Some(font) = cell.font() {
            println!("bold: {}", font.bold);
        }
        if let Some(fill) = cell.fill() {
            println!("fill: {}", fill.pattern_type);
        }
    }

    Ok(())
}

Writing

use oxlsx::{Color, Fill, Font, Workbook};

fn main() -> Result<(), oxlsx::OxlsxError> {
    let mut wb = Workbook::new();

    let ws = wb.active_mut().unwrap();
    ws.set_cell("A1", "Hello");
    ws.set_cell("B1", 42.0_f64);
    ws.set_cell("C1", true);
    ws.set_cell_font("A1", Font { bold: true, ..Default::default() });
    ws.set_cell_fill("A1", Fill {
        pattern_type: "solid".to_string(),
        fg_color: Some(Color::Argb("FFFF00".to_string())),
        bg_color: None,
    });

    wb.create_sheet("Data").set_cell("A1", "Sheet 2");

    wb.save("output.xlsx")?;
    Ok(())
}

API (openpyxl parity)

Benchmarks

Measured against openpyxl 3.1.2 on a 10k-row file (5 columns, mixed types). Absolute numbers are machine-dependent; the ratios are what matter. Reproduce with cargo bench + python3 benches/openpyxl_comparison.py.

Write

Read (10k rows, 5 cols)

For metadata or large-file streaming, use open_readonly() (lazy, ~20x faster than openpyxl). Eager open() loads the full sheet to enable random ws.cell("A1") access.

Run benchmarks yourself:

cargo bench                          # Rust (criterion)
python3 benches/openpyxl_comparison.py  # Python baseline

Data Model

Architecture

• SAX only — quick-xml event loop, no DOM, no full-file loading
• ZIP direct — reads from the container, no temp disk extraction
• Arc<StyleSheet> — shared across Workbook → Worksheet → Cell, no lifetime params
• PyO3-ready — all public structs are 'static compatible
• Newtype pattern — StyleId(usize) prevents index confusion at compile time

Dependencies

Roadmap

✅ Done

• ZIP container reading + SAX parsing
• Styles: fonts, fills, colors, StyleId newtype
• Shared strings → Value::String
• Value::Bool, Value::Date (resolved at parse time)
• Multi-sheet: wb.sheetnames(), wb.sheet_by_name(), ws.title()
• Write support: Workbook::new(), ws.set_cell(), wb.save()
• Style round-trip: bold font + solid fill survive write → open cycle
• Criterion benchmarks + openpyxl comparison script
• Streaming reader (open_readonly()), PyO3 bindings, read-modify-write
• Extended write: formulas, merged cells, column widths, date numFmt
• Iteration API (iter_rows/iter_cols/rows/columns/values, bounds)
• Bulk write (append, insert/delete rows/cols, move_range) — Rust + Python; merges/dims shift, table-intersection guard, formulas verbatim
• Rich formatting (number_format, alignment, border, protection)
• Hyperlinks + plain-text comments
• Freeze panes; print area / print titles
• Named ranges — wb.defined_names() (global) + ws.defined_names() (sheet-local), conservative lossless passthrough
• Tables — ws.add_table(), ws.tables, TableStyleInfo; lossless RMW (unmodeled table features preserved verbatim when untouched)
• Conditional formatting — FormulaRule / CellIsRule + Dxf; RMW-preserving (unmodeled rules kept verbatim)
• Sheet auto_filter; PatternFill + ws.set_cell_fill
• Utils — get_column_letter, column_index_from_string, dataframe_to_rows
• Distribution — abi3 wheels (CPython 3.8+), PyPI + crates.io, OIDC trusted publishing, release CI

🔲 Planned

• Phase 15 — Pandas engine / tabular adapter
  • engine="oxlsx" integration via a dedicated adapter
  • DataFrame ↔ XLSX mapping, headers/index handling, and type conversions
  • Explicit adapter instead of monkeypatching by default

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.