AWS ECS Express Mode¶

1. Create an ECS Express Mode Service¶

Go to the ECS console and select Express mode in the navigation pane on the left-hand side

Image URI:

public.ecr.aws/xlwings/xlwings-lite:1.0.0.0-68

Task execution role: Select an existing role or choose Create new role
Infrastructure role: Select an existing role or choose Create new role
Expand the Additional configurations section:
- Container port: 8000
- Environment variables > Add environment variable:
  - Key: XLWINGS_LICENSE_KEY
  - Value type: Environment variable
  - Value or value from: <your license key>
- CPU: 0.25 vCPU, Memory: 0.5 GB
- Networking: Configure according to your requirements (leaving the checkbox unchecked will expose the service to the public internet)
Click Create

2. Configuration (optional)¶

You can configure xlwings Lite via optional environment variables. For an overview, see Environment variables. To add environment variables to your existing service, click on your service > Update service (orange button on the top right) > Additional configurations. Once added, click on Update (orange button at the bottom right) to deploy.

3. Add-in installation¶

In your browser, go to https://<your-hostname>/manifest, which will download xlwings-lite-manifest.xml.
Go to Microsoft 365 admin center
- Click on Show all > Settings > Integrated Apps.
- If you have xlwings Lite installed, uninstall it first.
- Click on Upload custom apps and select Office Add-in (App type).
- 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 will get the add-in to show up automatically although it may take a few hours.

4. Hosting Pyodide separately (for production)¶

The xlwings Lite container ships with only the default version of the Pyodide distribution. When you upgrade the container, that version may change — and any workbook pinned to a previous Pyodide version will need to upgrade to the new Pyodide version.

In order to prevent this, you have to host the Pyodide distribution on S3 and point xlwings Lite at it. That way you can keep multiple Pyodide versions available indefinitely, and container upgrades become safe.

4.1 Launch the CloudFormation stack¶

A ready-made template creates an S3 bucket with CORS configured for Pyodide:

Download pyodide-hosting.yaml.
Go to the CloudFormation console, click Create stack > With new resources.
Select Upload a template file and upload the YAML file from step 1.
Give the stack a name (e.g., xlwings-pyodide).
Optional: in Parameters, set AllowedIpRanges to a comma-separated list of corporate egress CIDRs (e.g. 203.0.113.0/24,198.51.100.0/22) to limit access to your network. Leave empty for public read.
Click through to Submit. Wait for CREATE_COMPLETE, then open the Outputs tab. Note down BucketName and PyodideBaseUrl.

4.2 Upload a Pyodide release¶

Open AWS CloudShell (icon at the top of the AWS console). Wait for the prompt to appear.
Install bzip2:
```
sudo dnf install -y bzip2
```
Paste the following block, replacing BUCKET with the BucketName from the stack outputs. The first time you paste a multi-line block, CloudShell shows a “Paste multiple lines?” prompt — click Paste to confirm.
```
BUCKET=<your-bucket-name>
VERSION=0.27.5

curl -fL https://github.com/pyodide/pyodide/releases/download/${VERSION}/pyodide-${VERSION}.tar.bz2 | tar -xj
aws s3 sync pyodide/ s3://${BUCKET}/v${VERSION}/full/
rm -rf pyodide/
```
This might take a few minutes.

To keep additional Pyodide versions available, repeat step 3 with VERSION set to the desired version. Currently supported versions are:

0.27.5

4.3 Point xlwings Lite at the bucket URL¶

In your ECS service, add an environment variable:

Key: XLWINGS_PYODIDE_BASE_URL
Value: the PyodideBaseUrl from the stack outputs (e.g. https://my-bucket.s3.us-east-1.amazonaws.com)

After ECS redeploys, xlwings Lite will load Pyodide from S3 instead of the bundled copy.

5. Updating¶

To update xlwings Lite:

Go to the ECS console and navigate to your cluster > your service
Click on Update service (orange button on the top right). Update the Image URI to the following:
```
public.ecr.aws/xlwings/xlwings-lite:1.0.0.0-68
```
Once added, click on Update (orange button at the bottom right) to deploy.
Normally, you don’t need to update the manifest after deploying a new version of the container. Occasionally, this is required if e.g., if the URL of your container changed. In this case, the Office 365 admin center offers a link to Update Add-in.