ferroxl 0.2.0

ferroxl: read and write Excel 2007 xlsx/xlsm files with an openpyxl-compatible API
Documentation

ferroxl

A Rust library for reading and writing Excel 2007 .xlsx and .xlsm files.

ferroxl is a feature-parity port of openpyxl 3.1.5. It follows the Python package's module layout, class names and semantics, so a change can be traced back to the Python it mirrors. Where Python's behaviour cannot be reproduced in Rust — hash-based equality, tri-state booleans, PIL-backed images — the deviation is documented at the call site and the closest faithful behaviour is implemented instead.

This is the library crate. The MCP server that exposes it to AI agents is published separately as ferroxl-mcp.

Installation

[dependencies]

ferroxl = "0.2.0"

Rust 1.88 or newer, which is what rust-version in the manifest declares and what CI checks against.

Reading

use ferroxl::{load_workbook, LoadOptions};

let workbook = load_workbook("report.xlsx", LoadOptions::default())?;

for name in workbook.get_sheet_names() {
    println!("{name}");
}

let sheet = workbook.active_sheet()?;
for row in sheet.range_values("A1:D10")? {
    for value in row {
        println!("{value:?}");
    }
}
# Ok::<(), ferroxl::Error>(())

load_workbook_from_bytes takes an already-read buffer instead of a path, which is what a web service wants. LoadOptions carries guessing_types(), values_only() and keeping_vba() — inferring a cell's type from its text, returning Excel's last cached value instead of the formula, and keeping the original package bytes so a VBA project survives a save.

To walk the used range row by row rather than asking for a rectangle, iter_rows() and iter_cols() come back as whole rows and columns, so the outer and inner iterators always line up:

use ferroxl::{load_workbook, LoadOptions};

let workbook = load_workbook("report.xlsx", LoadOptions::default())?;
let sheet = workbook.active_sheet()?;

for row in sheet.iter_rows() {
    for cell in row {
        if let Some(cell) = cell {
            println!("{} = {:?}", cell.coordinate(), cell.internal_value());
        }
    }
}
# Ok::<(), ferroxl::Error>(())

Writing

use ferroxl::{CellValue, Workbook};

let mut workbook = Workbook::new();
let summary = workbook.create_sheet(Some("Summary"))?;
let sheet = &mut workbook.worksheets[summary];

sheet.set("A1", CellValue::text("Q3 revenue"))?;
sheet.set("B1", 150_000.0)?;
sheet.set("A2", CellValue::text("Total"))?;
sheet.set("B2", CellValue::formula("SUM(B1:B1)"))?;

workbook.save("report.xlsx")?;
# Ok::<(), ferroxl::Error>(())

Workbook::new() already makes a sheet called Sheet1, and create_sheet appends without making the new sheet active — openpyxl behaves the same way — so take the index create_sheet returns rather than reaching for active_sheet_mut, which would still be Sheet1. save consumes the workbook, which is what makes edit-then-save a single linear sequence; to_bytes returns the package instead, and save_workbook_to streams it to any Write.

Formula cells are written without a cached result by default, which is what openpyxl does. Excel calculates them on open; a reader that does not calculate will report the formula rather than a value. Use recalculate() or trace_precedents and trace_dependents to reason about the graph instead of assuming the numbers are there.

Formula evaluation

recalculate() evaluates every formula in the workbook and records the values, so a reader that is not Excel sees numbers rather than blanks:

# use ferroxl::{CellValue, Workbook};
let mut workbook = Workbook::new();
let sheet = workbook.active_sheet_mut().unwrap();
sheet.set("A1", CellValue::number(2.0)).unwrap();
sheet.set("A2", CellValue::number(3.0)).unwrap();
sheet.set("A3", CellValue::formula("=SUM(A1:A2)")).unwrap();

let report = workbook.recalculate();
assert_eq!(report.computed_count(), 1);
assert_eq!(workbook.active_sheet().unwrap().cached_value("A3"), Some(&CellValue::Number(5.0)));

It covers the operators, the aggregates, IF/IFERROR, AND/OR/NOT and the common text functions — 31 in all. A formula it cannot evaluate gets no cached value and is listed in Recalculation::unresolved with the reason, and formula::supports answers whether a name is handled without calling it and getting a wrong answer. calcPr/@fullCalcOnLoad is set, so Excel recomputes on open and a value the engine got wrong cannot survive a human opening the file.

Formulas are evaluated in one pass over reading order, so a formula reading another formula's cell sees it as blank. trace_precedents gives the order to do it properly.

Dependency tracing

The one thing openpyxl cannot answer is what a cell is connected to. ferroxl can:

# use ferroxl::{load_workbook, LoadOptions};
let workbook = load_workbook("model.xlsx", LoadOptions::default())?;
let sheet = workbook.active_sheet()?;

// What feeds D10, in the order a recalculation would visit them.
sheet.trace_precedents("D10")?;

// What breaks if B2 changes.
sheet.trace_dependents("B2")?;

// Excel refuses to calculate a workbook with one of these.
for cycle in sheet.circular_references()? {
    println!("{}", cycle.join(" -> "));
}
# Ok::<(), ferroxl::Error>(())

References through a defined name are reported rather than resolved, and a cross-sheet reference keeps its sheet title rather than being expanded. A guess at either would produce a graph that looks authoritative and is not.

Tables, named styles and charts

  • Tables (ListObjects) — Worksheet::add_table writes xl/tables/tableN.xml and the sheet tail that points at it, reading the column names out of the header cells so a structured reference like =SUM(Table1[Sales]) resolves.
  • Named styles — all 49 of Excel's built-ins as BUILTIN_DETAILS, generated from openpyxl's styles/builtins.py, plus Workbook::named_styles for a workbook's own. apply_named_style applies and registers, so the name reaches Excel's style gallery and reads back as cell.style.
  • Charts — all sixteen types, with series, axes, titles, error bars and 3-D views. Written, not read back: openpyxl 3.1.5's own reader does not parse chart parts either.

Round trips are not destructive

Workbook::preserved holds every part, content type, relationship and <workbook> / <worksheet> child that the writer does not produce, and the writer writes them back — so a pivot table, slicer, query table, threaded comment, ActiveX control or customXml part survives being opened and saved. Copying the bytes is the easy half: a part nothing points at is inert, so the relationship is preserved too, its id remapped where the writer has already used one, and the r:id in the referencing element rewritten to match.

Carrying a part through is not editing it. PARITY.md records what still does not survive: unknown attributes on <worksheet>, content inside <sheetData>, and byte-identical zip entries.

Streaming

save_dump writes rows as they are produced rather than building the sheet part as a String first, so peak memory is set by the largest row rather than the largest sheet:

# use ferroxl::Workbook;
let workbook = Workbook::new();
ferroxl::save_dump(workbook, &mut std::io::stdout())?;
# Ok::<(), ferroxl::Error>(())

crates/ferroxl/examples/build_and_read.rs is a full round trip — create a sheet, set cells, style a header, merge a range, freeze panes, save, load — in about a hundred lines:

$ cargo run --example build_and_read

Feature parity

PARITY.md in the repository tracks what is ported, what differs and why, and what is not ported at all. ROADMAP.md records proposals that were considered and declined, with the reasoning, so they do not have to be argued again.

Of openpyxl 3.1.5's 994 top-level public names, 678 have no counterpart and 32 of its 183 modules match in full. Not implemented: a read-only (read_only) loader, reading the stored <dimension> element, reading charts back, external-link parts, rich text, pivot tables, chart-only sheets, and the descriptors metaprogramming layer. The audit matches names rather than behaviour, so those figures are an upper bound on what works rather than a measurement of it — PARITY.md says so where it matters.

License

MIT, the same as openpyxl.