Quick start

You'll have your first custom function running in minutes

GitHub Actions

A shortcut is to use the xllify-starter template repo. You don't even need a Windows machine to work with it, just run your builds remotely. As the packaging step is very fast, a build should only take about 20-30 seconds from scratch.

Locally, it's instant - so read on.

Install for local builds

Packaging your builds locally during development makes more sense. You should still use the GitHub Action when building actual releases.

1

Get xllify

The xllify Packager is only available for Windows at this time.

Python

As is good practice, always work in a virtual environment. virtualenv works fine.

$ pip install virtualenv # if you don't have it
$ mkdir MyAddin
$ virtualenv venv
$ venv\Scripts\activate

$ pip install xllify
$ xllify-install

Requires ≥ Python 3.10 so ensure you have python available on your PATH (this is an option in the installer.)

Luau

As above, you can install through pip or download the xllify distribution from xllify.com and put the binary in your PATH.

2

Write some functions

It is a case of annotating/wrapping an ordinary function with a decorator. This allows you to provide metadata to Excel about the function and register it with xllify.

Parameters are automatically inferred, but you can provide additional metadata such as help text to fully populate the formula browser in Excel.

Python

my_functions.py

import xllify

@xllify.fn("xllipy.Hello")
def hello(name: str) -> str:
    return f"Hello, {name}!"

@xllify.fn("xllipy.Add", category="Math")
def add(a: float, b: float) -> float:
    return a + b

Luau

my_functions.luau

xllify.fn({
    name = "xllify.Hello"
}, function(name)
    return "Hello, " .. name .. "!"
end)

xllify.fn({
    name = "xllify.Add",
    category = "Math"
}, function(a, b)
    return a + b
end)

3

Check your functions (optional)

It's easier to test your functions outside of Excel.

Python

It is recommended you implement your Python functions independently using your existing dev-test workflow.

Keep your @xllify.fn decorated functions as thin 1-2 line wrappers that simply call independent implementations.

Luau

You can check your function works with the xllify-lua command. This tool also has a minimal testing framework. As with Python, you can make use of any Luau testing framework.

$ xllify-lua --load my_functions.luau
> call xllify.Add 5 10
Excel: =xllify.Add(5, 10)

15.000000

> list
> desc xllify.Add

4

Build your XLL

$ xllify MyAddin.xll my_functions.py       # Python
$ xllify MyAddin.xll my_functions.luau     # Luau

You can also mix both languages in a single XLL, if you want:

$ xllify MyAddin.xll calculations.luau data_fetch.py --py-entrypoint data_fetch

5

Load into Excel

Simply double-click the .xll file from Explorer. This will open the XLL in Excel. If you used Python, there will be a short delay while the virtual environment is configured.

6

Use your functions

The big moment. In an empty sheet try adding the following formulas.

=xllipy.Hello("World")    → Hello, World!
=xllipy.Add(5, 10)        → 15

=xllify.Hello("World")    → Hello, World!
=xllify.Add(5, 10)        → 15

Python functions show #N/A while processing, then update automatically when complete.

Adding dependencies (optional, Python only)

A big advantage to Python is the vast ecosystem. You can use any Python library you want, just create a requirements.txt file:

pandas>=2.0.0
numpy>=1.24.0
requests>=2.28.0

and add it to the build with:

$ xllify MyAddin.xll main.py --py-entrypoint main --py-requirements requirements.txt

Dependencies are installed automatically.