Excel Add-in
The Excel add-in APIs integrate Datatailr workflows with spreadsheet-based workflows.
Related API pages
Quick start: deploy your first Excel add-in
Step 1: write your Excel add-in
This example creates an add-in with two functions. Put it in a package, for
example my_addin/addin.py:
# my_addin/addin.py
from datatailr.excel import Addin
addin = Addin("MyAddin", "Adds and subtracts numbers")
@addin.expose(description="Adds 2 numbers", help="To add 2 numbers give them to the function")
def add(a: float, b: float) -> float:
return a + b
@addin.expose(description="Subtracts 2 numbers", help="To subtract 2 numbers give them to the function")
def sub(a: float, b: float) -> float:
return a - b
def main(port=8080, ws_port=8000):
addin.run(port, ws_port)
if __name__ == "__main__":
main()
main is the entrypoint of the deployment. Datatailr does not call it: the
platform imports the module that contains main and starts the Addin object
that this module creates. Keep the Addin object and main in the same
module. main and the if __name__ == "__main__": block let you
test the add-in in a workstation.
Step 2: deploy the Excel add-in
Put the deploy script outside the package:
# deploy.py
from datatailr import ExcelAddin
from my_addin.addin import main
addin = ExcelAddin(
name="my_addin",
entrypoint=main,
)
addin.save()
Run python deploy.py to deploy the add-in. save() sends the definition to
Datatailr, which builds the container image. When the build is done, the
add-in is on the Excel addins tab of the Launcher. Each user who opens it
gets a separate instance that runs as that user. In Excel, the functions are
=MYADDIN.ADD(1, 2) and =MYADDIN.SUB(5, 3). See
Excel Add-ins
for how users load the add-in into Excel.
Developing and deploying Excel add-ins
Excel add-ins on Datatailr are created automatically from Python modules. Any fully type-annotated functions you expose will be callable from Excel once the add-in is sideloaded.
Develop an Excel add-in
from datatailr.excel import Addin, Queue
Create the add-in
addin = Addin("MyAddin", "Adds and subtracts numbers")
Addin(...) parameters
- name: str - Display name in Excel. Without spaces, underscores and other
punctuation, it is also the prefix of the Excel function names.
"MyAddin"gives=MYADDIN.ADD(...). - description: str - Shown in the taskpane.
- version: str (optional), default value "1.0.0" - Semantic version.
- min_update_interval: float (optional), default value 0.5 - exists for compatibility with addins defined for v1. Doesn't do anything.
Expose functions
Decorate fully annotated functions with addin.expose(...).
Allowed type hints are plain int, float, list, bool, and str only.
Do not use generics (list[int]), unions (int | None), or other types
(dict, datetime, etc.) — the Excel bridge cannot map them and Excel will
report "Invalid argument" errors. For streaming functions, the first parameter
may be annotated queue: Queue; it is omitted from the Excel signature.
When you construct ExcelAddin(name=..., entrypoint=main, ...), the SDK parses
the entrypoint source file and raises ValueError if any @addin.expose(...)
function violates these rules.
import time
from datatailr.excel import Queue
@addin.expose(description="Add two numbers", help="Returns a + b")
def add(a: float, b: float) -> float:
return a + b
addin.expose(...) parameters
- description: str - Shown in the taskpane next to the function name.
- help: str - Tooltip shown in the formula bar.
- volatile: bool = False - Mark as volatile (Excel may recalc more often).
- streaming: bool = False - If True, the function's first argument must be
queue: datatailr.excel.Queue. The return value is ignored; values are sent viaqueue.push(...). - progressbar: bool = False - When True, the function becomes a streaming function that auto-streams a progress bar until the final result is ready.
Streaming functions
import time
from datatailr.excel import Queue
@addin.expose(
description="Simple numeric ticker",
help="Streams an increasing number",
streaming=True,
)
def int_ticker_N(queue: Queue, start: int, N: int) -> int:
value = start
for _ in range(N):
queue.push(value) # streamed to Excel immediately
value += 1
time.sleep(1)
# return value is ignored for streaming functions
Queue API
- Queue.push(value: Any) -> None - Streams a value to Excel. Type should match the function's annotated return type.
- Queue.error(message: str) -> None - Sends an error for the current invocation.
Working with matrices
Excel custom functions may accept and return 2-D lists ("matrices"). Elements may be mixed-type (strings, numbers, etc). Even 1-D vectors must still be represented as a 2-D nested list.
def print_row() -> list:
return [[1, 2, 3]]
def print_column() -> list:
return [[1], [2], [3]]
def print_matrix() -> list:
return [[1, 2], [3, 4]]
Optional parameters
If you define a default for a parameter, Excel treats it as optional. For
list-like parameters, use a plain list annotation and handle None inside
the function body (do not use list | None or Optional[list] in the hint):
def foo(x: list = None) -> list:
if x is None:
...
Test the add-in in a workstation
In a Datatailr workstation, run the add-in module from the folder that contains the package:
python -m my_addin.addin
main calls addin.run(8080, 8000), which starts the add-in server in the
workstation. The add-in builds its URLs from the workstation IDE proxy (the
VSCODE_PROXY_URI variable of the IDE terminal), so Excel can reach it.
addin.run() works only in a Datatailr workstation, because it starts the
add-in server program of the workstation image.
Addin.run(...) parameters
- port: int - HTTP port for the add-in page and non-streaming calls.
- ws_port: int - WebSocket port for streaming functions.
- ide: bool = True - Use the workstation IDE proxy for the add-in URLs. Keep
the default. With
ide=False, the add-in uses the URLs of a deployed add-in, and Excel cannot reach the add-in in the workstation.
Deploy an Excel add-in
Create an ExcelAddin and save it. Give it the main function of the add-in
module as the entrypoint. The ExcelAddin constructor checks the type hints
in the entrypoint source file (see Expose functions)
before it builds the job definition.
from my_addin.addin import main
from datatailr import ExcelAddin, Resources
addin = ExcelAddin(
name="my_addin",
entrypoint=main,
python_version="3.13",
resources=Resources(memory="512m", cpu=1.0),
)
addin.save()
Resources also accepts vram for GPU memory, using the same size strings as memory (for example "2g"). If you omit vram, the job definition omits the vram field.
When the image build is done, the add-in is on the Excel addins tab of the Launcher. A user who opens it there starts a separate instance of the add-in that runs as that user.
Note: The platform does not call the entrypoint function of an Excel add-in.
It uses the function only to find the module that creates the Addin object.