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). Recommended minimal specs: 1 vCPU, 1 GB RAM, 25 GB SSD.

  • A hostname pointing to the Linux VM, e.g., xlwings-lite.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.

  • Rclone installed on the VM:

    sudo -v ; curl https://rclone.org/install.sh | sudo bash

  • 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. If you don’t have one, you can request a trial key.

Install

1. Provide TLS certificates

Put your cert and key under /etc/xlwings-lite/certs/, named tls.crt and tls.key.

Typically your cert and key live on your local machine. Copy them to the VM with scp:

# From your local machine:
scp /path/to/your-cert.pem user@your-vm:/tmp/tls.crt
scp /path/to/your-key.pem  user@your-vm:/tmp/tls.key

Then on the VM, move them into place:

# On the VM:
sudo mkdir -p /etc/xlwings-lite/certs
sudo mv /tmp/tls.crt /tmp/tls.key /etc/xlwings-lite/certs/

If the cert is already on the VM, just sudo cp it into /etc/xlwings-lite/certs/ directly.

2. Install the xlwings-lite CLI

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

For an overview of the available commands, run:

xlwings-lite

3. Run the installer

sudo xlwings-lite install

Once install prints Running, visit https://<your-hostname> in your browser to confirm (the page shows the version of xlwings Lite).

4. Register the add-in with Microsoft 365 admin center

  1. In your browser, go to https://<your-hostname>/manifest, which will download 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, edit /etc/xlwings-lite/xlwings-lite.conf to set XLWINGS_HOSTNAME=<your-hostname>, then run sudo xlwings-lite restart, 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 hours. 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

To update xlwings Lite to the latest version, run:

sudo xlwings-lite update

Update the xlwings-lite CLI

To update the CLI, simply re-run the install command:

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 Environment variables for the full list of supported settings.

Download a Pyodide bundle

First, store the credentials you got by email (one-time):

sudo xlwings-lite pyodide configure --access-key <access-key> --secret <secret>

Then download the desired Pyodide bundle:

sudo xlwings-lite pyodide download --bundle-id <your-bundle-id> -v <pyodide-version>

You can pass -v (or --version) multiple times to download several Pyodide versions in one go. After the first successful customized download, --bundle-id is remembered in the config file and can be omitted on subsequent downloads.

Bundles are stored under /var/lib/xlwings-lite/pyodide/v<version>. They are automatically used after restarting xlwings Lite via sudo xlwings-lite restart.

Uninstall

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

You may also want to remove Docker, Docker images, and Rclone.

Troubleshooting

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