Skip to content

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 via queue.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.