Overview

This page is the starting point for deploying xlwings Lite on your own infrastructure. Self-hosting requires a Business or Enterprise plan, see pricing.

Why self-host?

If you rely on xlwings Lite for business-critical work, self-hosting gives you control over security, availability, and compliance:

  • Security: Your files are no longer served from a public internet servers that could get hacked, and users install dependencies from an internal PyPI (Python Package Index) mirror (e.g., Azure Artifacts) to guard against supply-chain attacks.

  • Privacy: Everything stays within your own network. Self-hosting even works on fully air-gapped systems with no internet access.

  • Reliability: No reliance on third-party services that the cloud add-in uses like jsDelivr, PyPI, Cloudflare, or Microsoft Azure—an outage on any of them won’t take your users down. And if Microsoft ever blocks the add-in or suspends the developer account it’s published under, your deployment keeps running.

  • Reproducibility: You host every file yourself, including the Python packages, so your workbooks keep working even if packages are deleted from PyPI.

  • Compliance: Keep all data on infrastructure you can audit, helping you meet requirements like GDPR, HIPAA, or SOC 2 and your own data-governance policies.

  • Additional features: Optionally allow users to access every web API through the baked-in CORS proxy. More features are planned.

  • Direct support: Self-hosting comes with direct support.

Architecture

xlwings Lite is an Office.js add-in powered by Pyodide, a Python distribution that runs in the browser via WebAssembly (Wasm). Office.js is Microsoft’s JavaScript-based add-in technology, and because it runs in the browser, the add-in’s files must be served from a server—this is exactly what you take over when you self-host. Since Python itself runs in the user’s browser rather than on the server, that server needs only minimal resources. The following illustration helps you understand how everything fits together:

        flowchart LR
  manifest[" (1) Manifest (XML)"]

  subgraph corp["Corporate Network"]
    direction LR

    subgraph user["End User (local computer)"]
      direction LR
      subgraph excel["Excel"]
        subgraph xlsx["xlsx file"]
          mainpy["(2) main.py"]
        end
      end
      subgraph browser["(3) Browser"]
        pyodide["Pyodide<br/>(Python)"]
      end
      excel <--> browser
    end

    subgraph docker["Docker Container"]
      direction TB
      caddy["(4) Caddy"] <--> static["Static Files"]
    end

    s3["(5) S3 Bucket"]
    pkgs["(6) Package Registry"]
  end

  manifest --> excel
  browser <--> caddy
  browser <--> s3
  caddy <--> pkgs

  classDef emphasis stroke:#000,stroke-width:3px;
  class user emphasis;

  1. Manifest (XML): A configuration file that defines the add-in’s button on the ribbon’s Home tab and points to the static file server—in this case, the Docker container. You install the add-in by uploading the manifest to the Microsoft 365 admin center.

  2. main.py: All files from xlwings Lite’s code editor, including main.py, are stored inside the workbook itself. This makes it behave just like VBA-enabled workbooks.

  3. Browser: Office.js add-ins run in an embedded browser—WebView2 on Windows and WKWebView on macOS. This is where Python runs via Pyodide.

  4. Caddy: The web server that serves the add-in’s static files. It also acts as an optional CORS proxy and an image cache (so custom functions can return images), and it handles access to internal PyPI registries such as Azure Artifacts.

  5. S3 Bucket: An S3-compatible bucket hosts the Pyodide runtime and its packages. For Linux VMs, this is served directly from disk.

  6. Packages Registry: We recommend serving Python packages from an internal PyPI mirror or proxy such as Azure Artifacts.

Hosting Solutions

xlwings Lite runs on any platform capable of running a Docker image. This includes Linux VMs, Kubernetes clusters, and container hosting services such as Azure Container Apps, AWS ECS/Fargate, or Google Cloud Run. Whichever platform you choose, see Configuration for the available settings.

Here are specific instructions for certain providers/hosting solutions: