Install Add-ins

An Office.js add-in is defined via its manifest, which is a simple configuration file in the XML format. There are 3 different ways how you can install a manifest in Excel:

Note

Each xlwings Server environment (dev, prod, …) has an own manifest as exposed via https://your.domain.com/manifest.

Sideloading

In a browser, go to https://YOUR_SERVER_URL/manifest. Copy the content and paste it in a file that you callxlwings-server-dev.xml or something similar.

Sideload the manifest according to the following instructions:

In Excel, go to Add-ins on the ribbon’s Home tab:

  • Windows: click on More Add-ins > Shared Folder. From here, you can install the add-in. Note that the add-in will stick around, even if you restart Excel.

  • macOS: you will see your add-in listed under Developer add-ins. Note that you will have to activate the add-in every time you restart Excel.

  • Web: The add-in will be available directly after uploading it.

Microsoft 365 admin center

  • In your Microsoft 365 admin center, click on Show all > Settings > Integrated Apps, then click on Upload custom apps.

  • As App type select Office Add-in.

  • Choose how to upload the app: the easiest way is to activate Provide link to manifest file and point to https://YOUR_SERVER_URL/manifest (make sure that this endpoint is publicly accessible and not e.g., only accessible internally). Click on Validate, then on Next where you’ll be able to select the users you want to deploy the add-in to. Alternatively, you can also copy/paste the content of https://<YOUR SERVER>/manifest into a file that you call xlwings-server-prod.xml or something similar, then upload it via Choose File.

The users should get the add-in to show up automatically although it may take a few minutes 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.

Note

If you want to remove the add-in again and run into issues (“Remove apps failed. No apps were successfully removed. Please try to remove them later.”), use this legacy URL: https://admin.microsoft.com/#/Settings/AddIns

Office add-in store (“AppSource”)

To publish an add-in to the Office add-in store, you will need to become a Microsoft Partner.

Make sure that you set the following setting with xlwings Server:

XLWINGS_CDN_OFFICEJS=true

This ensures that the office.js library will be loaded via CDN as per Microsoft’s requirements.

For further details, see Make your solutions available in Microsoft AppSource and within Office.

Clearing the Office cache

Sometimes, Excel gets confused when you update a manifest and it doesn’t show the changes correctly or opens a different version of the add-in. In these cases, clear the office cache:

  • On Windows, delete the following folders if they exist:

    %LOCALAPPDATA%\Microsoft\Office\16.0\Wef\
%USERPROFILE%\AppData\Local\Packages\Microsoft.Win32WebViewHost_cw5n1h2txyewy\AC\#!123\INetCache\

    then restart Excel.

  • On macOS, run the following in a Terminal:

    bash scripts/clear_office_cache_macos.sh

    then restart Excel.

Note

If you are sideloading an add-in and then want to move on to installing it via Microsoft 365 admin center or the Add-in Store, make sure to remove the sideloaded manifest and clearing the cache first!

Further reading