xllify Packager

The xllify tool is the compiler and is the most important part of the entire solution.

It packages Luau and Python scripts into Excel add-ins (XLL files) without needing a C compiler, libraries or any other dependencies. (A copy of Microsoft Excel is useful for testing your work. 👍)

Installation

Download from xllify.com or use pip, if you're working with Python.

$ pip install xllify && xllify-install

Note that this tool only runs on Windows. For Python add-ins, you and your end users will also need Python 3.10+ installed on your system.

Basic Usage

$ xllify <output.xll> [options] script1.luau script2.luau ...
$ xllify <output.xll> [options] script1.py script2.py ...

Options

• --py-entrypoint <module> - Python entrypoint module (default: main)

• --py-requirements <file> - Path to requirements.txt file to embed

• --help - Show help message

Examples

Luau only

xllify MyAddin.xll finance.luau forecasting.luau

Creates an XLL with Luau functions that run at native speeds inside Excel's process.

Python only

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

Creates an XLL with Python functions that run in an external process.

Mixed Luau and Python

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

Combines both:

• Luau functions run at native speeds inside Excel

• Python functions run in n external processes with full library access

• Both are available in Excel simultaneously

Development Workflow

For Luau

Rebuild the XLL whenever you change Luau code:

$ xllify MyAddin.xll finance.luau

Reload the XLL in Excel to see changes.

For Python

After building once, you can edit the extracted Python files directly:

# one off setup
pip install xllify
xllify-install

code main.py
<add some code>

# build
xllify MyAddin.xll main.py

<open MyAddin.xll in Excel and try function>

# cd into xll extraction dir and edit the live script
cd %LOCALAPPDATA%\xllify\MyAddin\python
code main.py

<make some changes and save>

Changes take effect when you reload the XLL or restart the Python process.

To force re-extraction after rebuilding, delete %LOCALAPPDATA%\xllify\MyAddin\ and reopen Excel.

Python entrypoint

The --py-entrypoint option specifies which Python module to run. This module should contain your @xllify.fn() decorated functions, or just import them.

If you have multiple Python files, include them all.

xllify MyAddin.xll main.py utils.py helpers.py --py-entrypoint main

The entrypoint module (main in this case) should import and register functions from other modules as needed.

Third-party dependencies

Use --py-requirements to bundle dependencies:

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

The requirements.txt file is embedded in the XLL and is automatically installed when the Python environment is set up on first load.

Note that if you specify a requirements.txt you need to include xllify as a dependency.

Output

The tool creates a single .xll file that can be loaded in Excel. This file contains:

• Compiled Luau bytecode (if any)

• Python scripts in a ZIP archive (if any)

• Function metadata for Excel registration

• Runtime flags set for the enablement async support

Troubleshooting

Command not found

Ensure xllify.exe is in your PATH or use the full path to the executable.

Python metadata extraction fails

• Install xllify-python: pip install xllify-python

• Ensure xllify-funcinfo is on your PATH

Luau parse errors

• Check your Luau syntax

• Ensure xllify.ExcelFunction() calls are properly formatted

Template extraction fails

The template XLL is embedded in xllify.exe - ensure the executable is not corrupted.