Formualizer
The fastest open-source spreadsheet engine. Native speed, from Python.
The shared Rust engine calculates a million-formula financial model in 0.26 seconds. See the benchmarks.
Load Excel workbooks, change inputs, recalculate and read results—in-process, with no Excel installation or office-suite service. Formualizer runs the calculation in Rust and gives you a Python API. Built for financial models, data pipelines and AI agents.
- No compromise on speed. Copied formulas compute as families over Arrow columns; lookups reuse indexes; only affected cells recalculate. See the benchmarks and methodology.
- Excel-compatible. 400+ functions, dynamic arrays,
LET,LAMBDA, names and cross-sheet references. Unlike a file reader, Formualizer computes formulas rather than just returning cached values. - Built for agents. Inspect dependencies, track edits with undo/redo, inject a clock and random seed, and expose typed inputs and outputs through SheetPort.
- Portable. Native wheels for Linux, macOS and Windows, plus a separate Pyodide build. The same engine also ships for Rust and JavaScript.
Need broader workbook editing CLI or MCP tools? Use agent-spreadsheet, built on Formualizer.
Installation
pip install formualizer
Prebuilt stable-ABI (abi3) wheels are published for Python 3.10 and newer on Linux (glibc and musl), macOS, and Windows. No Rust toolchain required.
Cooperative recalculation
Workbook.begin_recalc() returns a job with step(budget_ms=None), iter(budget_ms=5), prioritize(rectangles), cancel() and active. Use it as a context manager to cancel unfinished work on exit. Step reports include progress, changed rectangles and timing; read cell values separately. Rectangles are (sheet_name, r0, c0, r1, c1), 1-based and inclusive.
with wb.begin_recalc(priority=[("Summary", 1, 1, 20, 10)]) as job:
for report in job.iter(budget_ms=5):
print(report.phase, report.progress.cumulative)
# In an async function:
result = await wb.evaluate_async(
budget_ms=5, on_progress=lambda report: print(report.phase)
)
Native async steps run on a worker thread with the GIL released; callbacks run on the event loop. Admission and cancellation cleanup also run on workers. An atomic reservation makes a concurrent async driver fail promptly with RecalcAlreadyPendingError, including while a manual job is active or the first driver is still awaiting admission. Task cancellation waits for owned admission or the current step to stop, cancels any admitted job and re-raises. A new driver may begin after the prior driver returns. Pyodide yields between in-thread steps. Budgets are soft: families, cycles, graph construction and scheduling are indivisible. None means unlimited; zero still allows progress.
wb.recalc(5, on_step=callback) is the synchronous driver; return False to pause and resume through the returned outcome.job. Existing evaluate_* calls raise RecalcJobActiveError while a job is active. Reads and edits between steps are allowed; use has_pending_in_rect / pending_cells_in_rect with has_active_recalc_job to interpret old values. See the interruptible recalculation guide for lifecycle, exceptions and limits.
Runnable, self-contained examples (from this directory, with a compatible native build installed):
- Viewport grid: prioritize visible cells, scroll, repaint changed rectangles and edit an assumption during a job.
- Async service: keep a heartbeat running, cancel a superseded what-if request and calculate its replacement.
- Pause and inspect: pause a callback driver on a negative margin, repair the input and resume the same job.
Run, for example, python examples/interruptible_viewport_grid.py. Each script checks its final results; timings and step counts depend on the machine and native build.
Command line
Native wheels include the formualizer command, which recalculates the cached formula values in an .xlsx after another tool has edited it:
uvx formualizer recalc book.xlsx # run without installing
formualizer recalc book.xlsx --check --json # after pip install formualizer
python -m formualizer recalc book.xlsx --json # same CLI through the module
The CLI updates formula caches in place (or writes -o other.xlsx), preserving formula text and the rest of the workbook. Exit codes: 0 done, 1 error, 2 refused (unsupported workbook, nothing written), 3 --check found stale caches, 64 usage error, 130 interrupted. See the CLI reference. The CLI is not available in Pyodide; recalculate_xlsx_bytes is.
The same recalculation is available in-process:
import formualizer as fz
result = fz.recalculate_xlsx_file("book.xlsx") # in place
result = fz.recalculate_xlsx_file("book.xlsx", output="calculated.xlsx")
print(result["summary"]["status"], result["cache_cells_changed"])
A refusal raises RuntimeError("Unsupported feature: ... in ...") and writes nothing. The CLI's --json output carries the same refusal as structured feature/context fields, which is easier for agents to branch on.
For agents: edit with openpyxl, then recalc
openpyxl writes formulas but does not calculate them, and saving drops the cached values that data_only=True readers (and pandas) see. Recalc after the last save:
import json, subprocess, sys
from openpyxl import load_workbook
wb = load_workbook("book.xlsx")
wb.active["A1"] = 100 # edit inputs or formulas
wb.save("book.xlsx")
p = subprocess.run(
[sys.executable, "-m", "formualizer", "recalc", "book.xlsx", "--json"],
capture_output=True,
text=True,
)
r = json.loads(p.stdout)
if p.returncode == 2:
raise SystemExit(f"refused, do not retry: {r['refusal']}")
if p.returncode != 0:
raise SystemExit(r["message"])
print(r["status"], r["error_cells"], r["errors"]) # inspect formula errors
# Read the result; do not save again, or the caches are lost.
print(load_workbook("book.xlsx", data_only=True).active["B1"].value)
If errors lists unexpected cells, fix inputs or formulas, save and recalc again. Never save the data_only=True view: it would replace formulas with values. See the agent workflow guide and portable skill.
Documentation
Full documentation at formualizer.dev:
- Recalc CLI — recalculate
.xlsxcaches after openpyxl edits - Python Quickstart
- Python API Reference
- Function Reference — 400+ built-in functions
- SheetPort Guide — spreadsheets as typed APIs
- Workbook Edits and Batching
Quick start
Rows and columns are 1-based: row 3, column 2 is B3.
Create and calculate a model
import formualizer as fz
wb = fz.Workbook()
s = wb.sheet("Sheet1")
s.set_value(1, 1, fz.LiteralValue.number(1000.0)) # A1: principal
s.set_value(2, 1, fz.LiteralValue.number(0.05)) # A2: annual rate
s.set_value(3, 1, fz.LiteralValue.number(12.0)) # A3: periods
s.set_formula(1, 2, "=PMT(A2/12, A3, -A1)")
print(wb.evaluate_cell("Sheet1", 1, 2)) # ~85.61
Load an XLSX and evaluate
import formualizer as fz
# Use a workbook with Assumptions and Summary sheets.
wb = fz.load_workbook("financial_model.xlsx", strategy="eager_all")
wb.set_value("Assumptions", 3, 2, 0.07) # B3: change an input
wb.evaluate_all() # calculate affected formulas
print(wb.get_value("Summary", 5, 2)) # B5: read an output
# Optional native read-only mapping. The underlying file must not be
# destructively modified or truncated while it is loading.
mapped = fz.load_workbook(
"financial_model.xlsx",
path_source=fz.XlsxPathSource.DIRECT_MMAP,
)
Load and save XLSX bytes
import formualizer as fz
payload = open("financial_model.xlsx", "rb").read()
wb = fz.load_workbook_bytes(payload)
print(wb.evaluate_cell("Summary", 1, 2))
out = wb.to_xlsx_bytes()
All Python hosts, including Pyodide, use native by default for path-based and byte-oriented XLSX loading. backend="calamine" is a compatibility alias to native. Explicit umya rich reading and XLSX byte export remain available; native is read-only.
The native XLSX reader is the default for load_workbook, load_workbook_bytes, Workbook.from_path, Workbook.load_path, and Workbook.from_bytes. Filesystem loading supports the same SHARED_FILE and host-only DIRECT_MMAP path sources; the native backend is read-only.
wb = fz.load_workbook("financial_model.xlsx", backend="native")
wb_from_bytes = fz.Workbook.from_bytes(payload, backend="native")
Recalculate XLSX cached values (writeback)
import formualizer as fz
# in-place
summary = fz.recalculate_file("financial_model.xlsx")
print(summary["status"], summary["evaluated"], summary["errors"])
# write to a new file
summary = fz.recalculate_file(
"financial_model.xlsx", output="financial_model.recalc.xlsx"
)
Formula text is preserved. Cached-value typing follows the active
umya-spreadsheetimplementation.
Cache-only XLSX recalculation
result = fz.recalculate_xlsx_bytes(payload)
assert isinstance(result["bytes"], bytes)
print(result["summary"]["status"], result["cache_cells_changed"])
# The file API snapshots input and atomically replaces the destination on success.
result = fz.recalculate_xlsx_file("model.xlsx", output="model.recalc.xlsx")
# Reproducible TODAY/NOW and RAND, as with the CLI's --now/--tz/--seed:
from datetime import datetime, timezone
result = fz.recalculate_xlsx_file(
"model.xlsx",
output="model.recalc.xlsx",
rng_seed=7,
deterministic_timestamp_utc=datetime(2026, 1, 31, 9, tzinfo=timezone.utc),
deterministic_timezone="+01:00", # default UTC
)
print(result["clock"], result["seed"]) # what the run used, for replay
RAND is reproducible by default. Without deterministic_timestamp_utc,
TODAY/NOW use host local time; result["clock"]["now"] is the aware
datetime they saw.
These APIs use the shared cache-only Rust implementation, retaining formula text
and unrelated package members. Safe core resource limits apply;
error_location_limit= only caps retained error locations.
Calls to functions the engine does not implement (add-ins such as _xll.EURO,
VBA/macro functions) are written as #NAME?, not refused. The summary says why:
name = result["summary"].get("error_summary", {}).get("#NAME?")
if name:
for location, message in zip(name["locations"], name["messages"]):
print(location, message) # Sheet1!C4 Unknown function: _xll.EURO
print(result["summary"]["unknown_functions"]) # [{"name": "_xll.EURO", "cells": 1}]
messages is parallel to locations (None when a cell has no reason of its
own, e.g. an inherited #NAME?); unknown_functions is complete regardless of
error_location_limit. Numeric caches within one unit in the 15th significant
digit of the computed value are left untouched.
In Pyodide, recalculate_xlsx_bytes is available (not recalculate_xlsx_file
or the CLI). Pyodide has no system clock, so workbooks using TODAY/NOW are
refused unless deterministic_timestamp_utc is passed.
Supported inputs include ordinary/shared scalar formulas, supported calculation
names, new multi-cell spills from ordinary non-shared formulas, and existing
XLDAPR dynamic-array anchors with validated cm/array-ref metadata. Spills can
grow, shrink, collapse or become blocked; A1# and _xlfn.ANCHORARRAY(A1) read
the current spill. Source-declared children are generated caches, not independent
inputs: even externally edited child values are recalculated while their source
ownership remains declared. Obsolete caches are cleared, keeping styled shells.
formula_cells and summary["evaluated"] count source formulas/anchors, not
children. cache_cells_changed counts physical caches inserted, replaced or
cleared (including children), so it can exceed the formula count.
worksheet_parts_changed counts worksheets only, not metadata/relationships.
external_links ({"links_used": n, "refreshed": False, "policy": "cached"})
is present only when formulas read external workbook links; their values come
from the cache Excel stored in the workbook and are never refreshed. Pass
external_links="refuse" (default "cached", like the CLI's --external-links)
to raise OSError instead when any formula reads a link value; the policy is
decided after calculation and nothing is written. Workbooks whose links nothing
reads still recalculate. Other values raise ValueError.
Deterministic unchanged outputs recalculate to byte-identical no-ops.
Legacy fixed-extent (CSE) arrays, elementwise IF, Excel tables within a
validated subset, volatile functions and external links (read from the values
cached in the workbook, never refreshed) are recalculated too. Data tables,
unservable external references, rich/unknown or malformed metadata, hidden-row SUBTOTAL/AGGREGATE
ranges, circular references, shared-family multi-cell spills and spill
publication across merges are refused. Configured ZIP/XML/cell/output bounds
still apply. Fresh unmarked 1x1 results have no spill identity (A1# returns
#REF!); this is not a claim of Excel equivalence and no Excel execution oracle
was used. See the precise eligibility and publication contract.
The file API preserves existing destination permissions and leaves it untouched
on pre-publication failure; omitted output recalculates in place.
Source-aware calculation policy
The native library remains strict by default. Opt into source-aware settings and sparse admission explicitly:
result = fz.recalculate_xlsx_bytes(
payload,
profile="workbook",
calculation={
"workbookSeed": "18446744073709551615",
"fixedNowUtc": "2024-01-02T03:04:05Z",
"timezone": "utc",
"iterationInitialState": "require_verified",
},
require_complete=True,
)
recalculate_xlsx_file accepts the same keywords. The nested calculation mapping uses the shared camelCase source policy: iteration (mode: workbook|disabled|iterate, with optional maxIterations and maxChange for iterate), cycleDetection (runtime|static), workbookSeed (decimal u64 string or JS-safe integer), fixedNowUtc (RFC3339), timezone (utc|local|{"offsetSeconds": n}), maxElapsedMs, maxWorkUnits, and iterationInitialState (require_verified|cold_start). Unknown fields, invalid types and bounds fail before package loading. The workbook header always owns the date system.
Legacy deterministic keywords remain supported. With a source policy, explicit legacy seed, timestamp and timezone fill omitted nested fields; matching values are accepted and differing values raise ValueError. Legacy deterministic_timezone still requires legacy deterministic_timestamp_utc. Omitted legacy arguments never override nested values.
Results include canonical calculation settings/origins/warnings (or None on the legacy route), coverage, coverage_scope, caches_invalidated, calculation_flags_changed, and full operation_diagnostics (camelCase nested fields, including scoped function incidence, unavailable result cells and bounded samples). Complete coverage means no known gaps under the declared assumptions; it is not an Excel-equivalence guarantee. Partial results clear affected caches while retaining independent results.
require_complete=True rejects known gaps while allowing legitimate Excel error values. Catch fz.CalculationDeferred for typed reason and context; iterative source workbooks require verified initial state by default. Explicit cold_start uses a fresh evaluator state and is recorded as an assumption. Engine cancellation/resource failures retain ExcelEvaluationError fields; corrupt packages and output failures remain errors. A refusal never returns newly certified workbook bytes.
Both source routes accept limits=None and physical_telemetry=False. The native strict or workbook preset is selected before explicit legacy keywords and limits are merged. Neither calculation nor require_complete selects the workbook preset.
limits is a partial mapping with these camelCase fields: maxInputBytes, maxEntries, maxExpandedBytes, maxWorksheetBytes, maxFormulaCells, maxOutputBytes, maxXmlDepth, maxCells, maxColumns, maxOperationRoots, maxOperationTextBytes, maxAffectedWork, maxAffectedRegions, and maxAffectedScratchBytes. Missing fields preserve the preset and zero is an explicit bound. Counts and byte caps must be nonnegative integers within u32; maxColumns additionally cannot exceed 16384. maxAffectedWork must be a nonnegative JS-safe integer (at most 9007199254740991). Strings, booleans, fractions, arrays and null fields are invalid. Top-level None means no override. Invalid options fail before ZIP loading or destination access.
Evidence roots/text and affected-query work/output/scratch exhaustion are fatal ExcelEvaluationError failures, including with error_location_limit=0 or require_complete=False. Operation text bytes measure retained owned evidence text; scratch measures requested query capacity, not process RSS. Dependency evidence reports admitted query work plus the conservative publication membership work bound separately from queryWork. Its scope is the admitted workbook and fixed cached sources, with explicit semantic-read and unknown-dynamic caveats; it does not certify arbitrary provider reads or total CPU use.
operation_diagnostics.functionModes and typed samples preserve unavailable modes, unverified modes and providers. Executed uncertainty (including caught gaps) prevents complete coverage; inactive branches and ordinary Excel errors alone do not. Samples can be truncated without dropping logical safety evidence. Default physicalFunctionDispatches and physicalUnavailableObservations are present as None (unmeasured). Explicit telemetry reports measured zero or positive counters; counters above the JS-safe domain use exact decimal strings. These counters are diagnostic and do not determine coverage.
The package exports SourceCalculationPolicy, SourceRecalculateLimits, SourceRecalculateResult, SourceOperationDiagnostics, SourceUnavailableOperation, and SourceDependencyEvidence typing records. Generated source function stubs use these request/result shapes; runtime validation remains canonical Rust serde and policy validation.
Parse and analyze formulas
from formualizer import parse
from formualizer.visitor import collect_references, collect_function_names
ast = parse("=SUMIFS(Revenue,Region,A1,Year,B1)")
print(ast.pretty()) # indented AST tree
print(ast.to_formula()) # canonical Excel string
print(collect_references(ast)) # [Revenue, Region, A1, Year, B1]
print(collect_function_names(ast)) # ['SUMIFS']
Key features
| Capability | Description |
|---|---|
| Tokenization | Break formulas into structured Token objects with byte spans and operator metadata |
| Parsing | Produce a rich AST with reference normalization, source tracking, and 64-bit structural fingerprints |
| 400+ built-in functions | Math, text, lookup (XLOOKUP, VLOOKUP), date/time, financial, statistics, database, engineering |
| Workbook evaluation | Set values and formulas, evaluate cells/ranges, load XLSX/CSV/JSON |
| XLSX cache writeback | recalculate_file(path, output=None) recalculates formulas and writes cached values back |
| Batch operations | set_values_batch / set_formulas_batch for efficient bulk updates |
| Undo / redo | Optional changelog with automatic action grouping — single edits are individually undoable |
| Evaluation planning | Inspect the dependency graph and evaluation schedule before computing |
| SheetPort | Treat spreadsheets as typed functions: manifests built in code or YAML, schema validation, and batch scenarios |
| Deterministic mode | Inject clock, timezone, and RNG seed for reproducible evaluation |
| Visitor utilities | walk_ast, collect_references, collect_function_names for ergonomic tree traversal |
| Rich errors | Typed TokenizerError / ParserError / ExcelEvaluationError with position info |
Workbook evaluation
import formualizer as fz
wb = fz.Workbook()
s = wb.sheet("Data")
# Set values and formulas
s.set_value(1, 1, fz.LiteralValue.number(100.0))
s.set_value(2, 1, fz.LiteralValue.number(200.0))
s.set_value(3, 1, fz.LiteralValue.number(300.0))
s.set_formula(4, 1, "=SUM(A1:A3)")
s.set_formula(4, 2, "=AVERAGE(A1:A3)")
print(wb.evaluate_cell("Data", 4, 1)) # 600.0
print(wb.evaluate_cell("Data", 4, 2)) # 200.0
Custom functions
Register workbook-local callbacks without forking Formualizer:
import formualizer as fz
wb = fz.Workbook(mode=fz.WorkbookMode.Ephemeral)
wb.add_sheet("Sheet1")
wb.register_function(
"py_add",
lambda a, b: a + b,
min_args=2,
max_args=2,
)
wb.set_formula("Sheet1", 1, 1, "=PY_ADD(20,22)")
print(wb.evaluate_cell("Sheet1", 1, 1)) # 42
print(wb.list_functions())
wb.unregister_function("py_add")
Key semantics:
- Names are case-insensitive and stored canonically (
py_add->PY_ADD). - Custom functions are workbook-local and take precedence over global built-ins.
- Built-in override is disabled by default; set
allow_override_builtin=Trueto opt in. - Args are passed by value; range inputs arrive as nested Python lists.
- Return Python primitives, datetime/date/time/timedelta, dict error objects, or nested lists for array spill output.
- Python callback exceptions are sanitized and mapped to
#VALUE!.
Runnable custom-function example (from a source checkout: python bindings/python/examples/custom_function_registration.py).
Batch operations
# Bulk-set values (auto-grouped as one undo step when changelog is enabled)
s.set_values_batch(
1,
1,
3,
2,
[
[fz.LiteralValue.number(10.0), fz.LiteralValue.number(20.0)],
[fz.LiteralValue.number(30.0), fz.LiteralValue.number(40.0)],
[fz.LiteralValue.number(50.0), fz.LiteralValue.number(60.0)],
],
)
Undo / redo
The changelog is opt-in. Once enabled, every edit is tracked:
wb.set_changelog_enabled(True)
s.set_value(1, 1, fz.LiteralValue.number(10.0))
s.set_value(1, 1, fz.LiteralValue.number(20.0))
wb.undo() # back to 10
wb.redo() # back to 20
# Batch methods are auto-grouped as one undo step.
# For manual grouping of multiple calls:
wb.begin_action("update prices")
s.set_value(1, 1, fz.LiteralValue.number(100.0))
s.set_value(2, 1, fz.LiteralValue.number(200.0))
wb.end_action()
wb.undo() # reverts both values at once
Evaluation planning
Inspect what the engine will compute before running:
plan = wb.get_eval_plan([("Sheet1", 1, 2)])
print(f"Vertices to evaluate: {plan.total_vertices_to_evaluate}")
print(f"Parallel layers: {plan.estimated_parallel_layers}")
for layer in plan.layers:
print(f" Layer: {layer.vertex_count} vertices, parallel={layer.parallel_eligible}")
# By default this will build deferred workbook graphs if needed.
# Disable that behavior if you want planning to fail instead of mutating workbook state.
wb.get_eval_plan([("Sheet1", 1, 2)], build_graph_if_needed=False)
SheetPort: spreadsheets as typed APIs
SheetPort turns a workbook into a function. A manifest names its input and output cells with their types and constraints; a session writes validated inputs, recalculates and returns typed outputs. Build the manifest with formualizer.sheetport, pass a plain dict with the same structure, or load it from YAML.
import formualizer as fz
from formualizer.sheetport import Input, Manifest, Output
# The model: B4 computes the monthly payment from B1:B3.
wb = fz.Workbook() # or fz.load_workbook("loan.xlsx")
wb.add_sheet("Calculator")
wb.set_formula("Calculator", 4, 2, "=PMT(B2/12, B3, -B1)")
manifest = Manifest(
"loan-calculator",
name="Loan calculator",
ports=[
Input("principal", "Calculator!B1", type="number", constraints={"min": 0}),
Input("rate", "Calculator!B2", type="number"),
Input("term_months", "Calculator!B3", type="integer"),
Output("monthly_payment", "Calculator!B4", type="number"),
],
)
session = fz.SheetPortSession(wb, manifest)
session.write_inputs({"principal": 250_000, "rate": 0.045, "term_months": 360})
outputs = session.evaluate_once(freeze_volatile=True)
print(outputs["monthly_payment"]) # 1266.71...
A rejected update raises SheetPortConstraintError and writes nothing. Input and Output take the port id and a location: a string is an A1 reference, name("Rate") selects a defined name and layout(...) the rows under a header. type= declares a single cell; schema=range_of(...), record_of(...) or table_of(...) declares a larger shape.
A table port reads and writes a list of rows:
import formualizer as fz
from formualizer.sheetport import Input, Manifest, Output, column, layout, table_of
wb = fz.Workbook()
wb.add_sheet("Orders")
for col, header in enumerate(["sku", "quantity", "unit_price"], start=1):
wb.set_value("Orders", 1, col, header)
wb.set_formula("Orders", 1, 6, "=SUMPRODUCT(B2:B1000, C2:C1000)") # F1: order total
manifest = Manifest(
"order-total",
ports=[
Input(
"lines",
# Rows below the header in A1, until the first blank row.
layout(
sheet="Orders",
header_row=1,
anchor_col="A",
terminate="first_blank_row",
),
schema=table_of(
columns=[
column("sku", "string"),
column("quantity", "integer"),
column("unit_price", "number"),
],
keys=["sku"],
),
),
Output("total", "Orders!F1", type="number"),
],
)
session = fz.SheetPortSession(wb, manifest)
session.write_inputs(
{
"lines": [
{"sku": "A-100", "quantity": 3, "unit_price": 12.5},
{"sku": "B-200", "quantity": 1, "unit_price": 40.0},
]
}
)
print(session.evaluate_once()["total"]) # 77.5
To ship the manifest as a file instead, write it once with manifest.to_yaml() and load it with SheetPortSession.from_manifest_yaml(text, wb), or SheetPortSession.from_manifest_path(manifest_path, workbook_path) to open both files. The manifest format documents every field.
API reference
Top-level functions
tokenize(formula: str, dialect: FormulaDialect = None) -> Tokenizer
parse(formula: str, dialect: FormulaDialect = None) -> ASTNode
load_workbook(path: str, strategy: str = None, *, backend: str | None = None, path_source: XlsxPathSource | None = None, span_evaluation: bool | None = None) -> Workbook
load_workbook_bytes(data: bytes, strategy: str = None, backend: str | None = None, *, span_evaluation: bool | None = None) -> Workbook
recalculate_file(path: str, output: str | None = None) -> dict
recalculate_xlsx_bytes(data: bytes, *, error_location_limit: int | None = None, rng_seed: int | None = None, deterministic_timestamp_utc: datetime | None = None, deterministic_timezone: str | int | None = None, external_links: str = "cached") -> dict
recalculate_xlsx_file(path: str, output: str | None = None, *, error_location_limit: int | None = None, rng_seed: int | None = None, deterministic_timestamp_utc: datetime | None = None, deterministic_timezone: str | int | None = None, external_links: str = "cached") -> dict
Core classes
Workbook— create, load, evaluate, undo/redo. Supportsfrom_path(),from_bytes(),load_path(), andto_xlsx_bytes().Sheet— per-sheet facade forset_value,set_formula,get_cell, batch operations.LiteralValue— typed values:.int(),.number(),.text(),.boolean(),.date(),.time(),.datetime(),.duration(),.empty(),.error(),.array().Tokenizer— iterable token sequence with.render()and.tokens.ASTNode—.pretty(),.to_formula(),.fingerprint(),.children(),.walk_refs().CellRef/RangeRef/TableRef/NamedRangeRef— typed references.SheetPortSession—SheetPortSession(workbook, manifest)binds a manifest to a workbook; read/write typed ports, evaluate. Alsofrom_manifest_yamlandfrom_manifest_path.formualizer.sheetport—Manifest,Input,Outputand location/schema helpers for building manifests in code.EvaluationConfig— tune parallel evaluation, warmup, range limits, date systems.
Visitor helpers (formualizer.visitor)
walk_ast(node, visitor_fn) # DFS with VisitControl (CONTINUE/SKIP/STOP)
collect_references(node) # -> list[ReferenceLike]
collect_function_names(node) # -> list[str]
collect_nodes_by_type(node, "Function") # -> list[ASTNode]
Full type stubs are included in the package (.pyi files) for IDE autocompletion and mypy.
Building from source
Requires Rust 1.99.0 (the pinned release toolchain; edition 2024) and maturin:
pip install maturin
cd bindings/python
maturin develop # debug build
maturin develop --release # optimized build
Using in Pyodide (browser / WebAssembly)
Native wheels are published to PyPI. Pyodide wheels are built and smoke-tested in CI and release workflows, then uploaded only as the wheels-pyodide Actions artifact; they are not uploaded to PyPI or attached to GitHub Releases. Download and extract the artifact (or build locally), then host the compatible wheel at a browser-accessible URL with suitable CORS headers. An Actions artifact ZIP is not a wheel URL:
import micropip
wheel_url = "<your-downloadable-wheel-url>"
await micropip.install(wheel_url)
import formualizer as fz
wb = fz.Workbook()
wb.add_sheet("Sheet1")
wb.set_value("Sheet1", 1, 1, 20)
wb.set_value("Sheet1", 2, 1, 22)
wb.set_formula("Sheet1", 1, 2, "=SUM(A1:A2)")
wb.evaluate_cell("Sheet1", 1, 2) # -> 42.0
Tested Pyodide target: CI and release smoke tests use Pyodide 314.0.7 (Python 3.14) and the wheel's derived platform tag (currently pyemscripten_2026_0_wasm32). Wheels for this ABI do not install in Pyodide 0.29.x (pyodide_2025_0). Rebuild and smoke-test a wheel when targeting another runtime; no persistent public wheel URL is promised.
Pyodide-specific behavior:
EvaluationConfig()andWorkbook()defaultenable_parallel = Falseonsys.platform == "emscripten"(Pyodide has no threads). You can still opt in, but it falls back to single-threaded execution.- XLSX byte loading defaults to
nativeon every host, including Pyodide;calamineis a compatibility alias. XLSX byte export usesumyaon all platforms. - Source-preserving recalculation is available as
recalculate_xlsx_bytes(the CLI andrecalculate_xlsx_fileare not). There is no system clock: workbooks usingTODAY/NOWare refused unlessdeterministic_timestamp_utcis passed, andresult["clock"]["now"]isNoneotherwise. - Python UDFs registered via
Workbook.register_functionwork identically to native; single-cell refs arrive as scalars (Excel-native semantics).
Building a Pyodide wheel from source
For local development or targeting a Pyodide version without a retained Actions artifact:
./scripts/build-pyodide-wheel.sh
./scripts/smoke-pyodide-wheel.sh dist/pyodide/*_wasm32.whl
The build script defaults to xbuildenv Pyodide 314.0.7, derives Python, ABI, Emscripten, and Rust toolchain values from pyodide config, installs that Rust toolchain's wasm32-unknown-emscripten target (or, for an xbuildenv that names one, Pyodide's custom wasm-EH sysroot), and tags the output wheel with the platform tag Pyodide's micropip expects. pyodide-cli and pyodide-build are resolved through uvx and are not pinned by the script.
Testing
pip install formualizer[dev]
pytest bindings/python/tests
ruff check bindings/python
mypy bindings/python/formualizer
Workspace layout
formualizer/
crates/ # Rust core (parse, eval, workbook, sheetport)
bindings/python/
formualizer/ # Python package (helpers, visitor, type stubs)
src/ # PyO3 bridge (Rust -> Python)
The Python wheel links directly against the Rust crates — there is no runtime FFI overhead beyond the initial C-to-Rust boundary.
License
Dual-licensed under MIT or Apache-2.0, at your option. Both license texts ship inside the package.
Metadata
Release files for formualizer 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| formualizer-0.15.0.tar.gz | 3.7 MB | Without provenance | Details for formualizer-0.15.0.tar.gz |
Built distributions (wheels)
Total release size: 65.8 MB
Release files / formualizer-0.15.0.tar.gz
| Download URL | formualizer-0.15.0.tar.gz |
|---|---|
| Size | 3.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48c7119806f89eaaf3d5640eca77a094c15efb5e96cbe0947f22aa68420cc65e
|
|
BLAKE2b-256 checksum How to use checksums |
0a3d042540b10c5724d1584bce0d25831dabdc7518ccb74b33e12f447ed1eac1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-win_amd64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
75c3a67b7cf794d042069f94ff7e5759e492ad290179c9636a23f0b2369af13f
|
|
BLAKE2b-256 checksum How to use checksums |
2fee2d2947d7c9b8733effa54936340640df9b622b5669f6ca7b1d1e3040b381
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-musllinux_1_2_x86_64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.10 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
fbcaec30c9443a5600e2dcef8a0cc85f351003adfb294418e370263126fdc07e
|
|
BLAKE2b-256 checksum How to use checksums |
0af9fa0fbfe1b1858fbf6644dc0e2bf982aee0d4f738c0b5f3872196db180ae2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-musllinux_1_2_aarch64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.10 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
d02e0e8ee855a88628e85072fd4f4495f3b6bfa1320519587e6eff74f7eb3865
|
|
BLAKE2b-256 checksum How to use checksums |
694c92435bfb54a16f3556179b37345bdee879c8fff1a242bb37161b30a49319
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.1 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d2afe0e197d730559502b57d1e7ee4d35bddc42b58627e4f628684d4b5038bd1
|
|
BLAKE2b-256 checksum How to use checksums |
119cfb5064ea01fe89115011d8e98050ec4497a6b53e14e174a7753996235453
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
edb251f513884bfaa82bf3f912eed6682e463fcaef685f30813acbd455ef71f3
|
|
BLAKE2b-256 checksum How to use checksums |
e52ab635389090ef14328877aa3bcc786c2b9a05687242f78a8ad8c2fb62e5c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.3 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
81d6fc9b28fde550a65bbdfc07b619c184b553805b0c86b4877b010616a807c9
|
|
BLAKE2b-256 checksum How to use checksums |
fff744828f3e0b6144ee448ed5b7a4dc005bc83eb3bdc86ade3fb8d840a71bf9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / formualizer-0.15.0-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | formualizer-0.15.0-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4c3bf3c0a9a7973a319f2473665bd94a012e8b7b7e8de27d6d1b4586e1e95285
|
|
BLAKE2b-256 checksum How to use checksums |
b4f660a0f81dcec3350c93b57dd42023a6b12b76ed92ab7c9fc470b69470a332
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for formualizer 0.15.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.