Formulas

1.3.4 · active · verified Wed Apr 15

Formulas is a Python library that implements an interpreter for Excel formulas, parsing and compiling Excel formula expressions. It can also compile Excel workbooks to Python code and execute them without needing a Microsoft Excel COM server. The current version is 1.3.4, released on March 11, 2026, with an active, though irregular, release cadence.

Warnings

gotcha To work with Excel workbooks (e.g., loading, calculating, writing Excel files via `ExcelModel`), you must install the `formulas` library with the `excel` extra. Use `pip install formulas[excel]` or `pip install formulas[all]`.
Fix: Ensure installation with `pip install formulas[excel]` or `pip install formulas[all]` if `ExcelModel` is used.
gotcha The library's interpretation of complex Excel formulas, especially those with empty parameters or nuanced operator precedence, has evolved. Formulas that rely on edge-case behaviors might produce different results across minor versions due to internal parser corrections.
Fix: Thoroughly test existing complex formulas after upgrading the `formulas` library to ensure consistent behavior. Refer to the project's changelog for specific parser adjustments.
gotcha When defining custom functions, they must be explicitly registered with the `formulas.get_functions()` dictionary. Forgetting this step will lead to formula parsing errors when the custom function is referenced.
Fix: Always retrieve the global functions dictionary using `formulas.get_functions()` and assign your custom function to a key (its Excel name) within that dictionary before parsing formulas that use it.

Install

pip install formulas Core library
pip install formulas[all] With all optional features (Excel model, plotting, web server)

Imports

Parser
```
from formulas import Parser
```
ExcelModel
wrong:
```
from formulas.excel import ExcelModel
```
correct:
```
from formulas import ExcelModel
```
ExcelModel is directly available from the top-level 'formulas' package after installation of the 'excel' extra.

get_functions

import formulas
functions = formulas.get_functions()

Quickstart

This quickstart demonstrates how to parse and compile a basic Excel formula using the `Parser` class and how to extend the interpreter with custom Python functions. It showcases two core capabilities of the library: formula evaluation and customization.

import formulas

# 1. Parse and compile a simple Excel formula
parser = formulas.Parser()
ast_node = parser.ast("=SUM(10, 20)")[1] # [1] gets the formula node
compiled_func = ast_node.compile()
result_sum = compiled_func() # Expected: 30
print(f"Result of '=SUM(10, 20)': {result_sum}")

# 2. Add a custom function
FUNCTIONS = formulas.get_functions()
FUNCTIONS['MYCUSTOMADD'] = lambda x, y: x + y + 100

custom_func_node = parser.ast("=MYCUSTOMADD(5, 7)")[1]
compiled_custom_func = custom_func_node.compile()
result_custom = compiled_custom_func() # Expected: 5 + 7 + 100 = 112
print(f"Result of '=MYCUSTOMADD(5, 7)': {result_custom}")

view raw JSON →