xllify-build

xllify.com is the easiest way to add very high performance custom functions to Microsoft Excel. It takes functions implemented as Luau and/or Python scripts and compiles them into custom functions packaged as an .xll Excel add-in. You can sell, distribute and deploy this .xll however you wish.

Note that currently only Microsoft Excel on Windows is supported. Mac support will involve some (!) compromises, but may follow if there's demand.

There's a starter template repository to help you get started in under a minute, and more examples in the demo repository.

Support

Drop an email to [email protected].

Usage

Here is a workflow to get you started with this action. It compiles black_scholes.luau, hello.luau and the_answer.luau into a ready to run .xll add-in named hello.xll.

After the build has completed, it is available in your workspace at the path held in ${{ steps.xllify.outputs.xll_path }}. A common approach is to attach it to a release, as is done below.

name: Build XLL Add-in

on:
  push:
    tags:
      - "v*"

jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build XLL with xllify
        id: xllify
        uses: acornsoftuk/[email protected] # use version
        with:
          xll_filename: hello
          embed_scripts: |
            hello.luau
            the_answer.luau
            black_scholes.luau
          xllify_key: ${{ secrets.XLLIFY_KEY }}

      - name: Upload XLL to release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ steps.xllify.outputs.xll_path }}

Example with Python

name: Build XLL Add-in with Python

on:
  push:
    tags:
      - "v*"

jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build XLL with xllify
        id: xllify
        uses: acornsoftuk/[email protected] # use version
        with:
          xll_filename: my_python_addin
          embed_scripts: |
            functions.py
            helpers.py
          python_entrypoint: main.py
          python_requirements: requirements.txt
          xllify_key: ${{ secrets.XLLIFY_KEY }}

      - name: Upload XLL to release
        uses: softprops/action-gh-release@v1
        with:
          files: ${{ steps.xllify.outputs.xll_path }}

Inputs

embed_scripts (required)

Space or newline-separated list of .luau and/or .py script file paths relative to your repository root.

xll_filename (optional)

Name of the output XLL file (without extension). Defaults to MyAddin. The .xll extension will be added automatically if not provided.

addin_name (optional)

Internal name for the add-in project. Defaults to MyAddin.

xllify_version (optional)

Version of xllify distribution to use. Defaults to 0.5.2.

xllify_key (optional)

License key for xllify. Defaults to early-adopter.

python_entrypoint (optional)

Name of Python entrypoint file. Only used when Python scripts are included in embed_scripts.

python_requirements (optional)

Path to Python requirements.txt file. Only used when Python scripts are included in embed_scripts.

Outputs

xll_path

Path to the built XLL file (relative to workspace).

test_results_path

Path to test results XML file.

Caveats

• .xll files are not signed and can only run from safe locations. xllify XLLs may trigger a warning when you load them into Excel, depending upon your environment. This is all explained here: https://support.microsoft.com/en-gb/topic/excel-is-blocking-untrusted-xll-add-ins-by-default-1e3752e2-1177-4444-a807-7b700266a6fb about ways to work around this for now. Examples of using your own signing certificates are coming soon.