Linux VM

This guide shows how to self-host xlwings Lite on a plain Linux VM using the xlwings-lite CLI.

Prerequisites

  • A Linux VM (e.g., Ubuntu 24.04 LTS).

  • Minimal specs: 1 vCPU, 1 GB RAM, 25 GB SSD.

  • A hostname pointing to the Linux VM, e.g., xlwings.mycompany.com.

  • Docker installed on the VM:

    curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh

    If this doesn’t work, follow Docker’s official installation guide.

  • A TLS certificate and private key for your hostname (xlwings Lite is an Office.js add-in, which requires this even when hosted internally).

  • An xlwings license key.

Install

1. Place your TLS certificates

Put your cert and key under /etc/xlwings-lite/certs/. The default filenames are tls.crt and tls.key:

sudo mkdir -p /etc/xlwings-lite/certs
sudo cp /path/to/your-cert.pem /etc/xlwings-lite/certs/tls.crt
sudo cp /path/to/your-key.pem  /etc/xlwings-lite/certs/tls.key

2. Install the CLI

sudo curl -fsSL https://lite.xlwings.org/cli -o /usr/local/bin/xlwings-lite
sudo chmod +x /usr/local/bin/xlwings-lite

3. Run the installer

sudo xlwings-lite install

Once install prints Running., visit https://<your-hostname>/ in your browser to confirm.

4. Register the add-in with Microsoft 365

  1. In your browser, open https://<your-hostname>/manifest and save the file when prompted (it downloads as xlwings-lite-manifest.xml). Open the XML file in an editor and double-check that e.g., <IconUrl> contains the correct URL. If it doesn’t, set the environment variable XLWINGS_HOSTNAME with the correct domain name, see Environment variables.

  2. Go to Microsoft 365 admin center

    • Click on Show all > Settings > Integrated Apps, then click on Upload custom apps.

    • As App type select Office Add-in.

    • Select Upload manifest file (.xml) from device. Click Choose File, then select the xlwings-lite-manifest.xml from the previous step.

    • Click Next, then assign the desired users.

    • Click Next and accept permission requests.

    • Click Next and Finish deployment.

The users should get the add-in to show up automatically although it may take a few minutes/hours until they show up. Alternatively, they can go to Add-ins on the ribbon’s Home tab and click on More Add-ins. They will see the add-in under the tab Admin Managed from where they can install it (there’s also a Refresh button at the top right).

Operations

Update xlwings Lite

sudo xlwings-lite update

Update the CLI

Re-run the install commands to overwrite the script in place:

sudo curl -fsSL https://lite.xlwings.org/cli -o /usr/local/bin/xlwings-lite
sudo chmod +x /usr/local/bin/xlwings-lite

Edit the configuration

The config file is /etc/xlwings-lite/xlwings-lite.conf. After editing, run sudo xlwings-lite restart to apply. See Overview for the full list of supported settings.

Uninstall

sudo xlwings-lite stop
sudo rm -rf /etc/xlwings-lite
sudo rm /usr/local/bin/xlwings-lite

Troubleshooting

  • cannot talk to the docker daemon — Start Docker: sudo systemctl start docker.