Sideload Office Add-ins that use the unified manifest for Microsoft 365

The process of sideloading an add-in that uses the Unified manifest for Microsoft 365 varies depending on the tool you want to use and on how the add-in project was created.

Note

An add-in that uses the unified manifest can be sideloaded on Office on Windows, Version 2304 (Build 16320.20000) or later. Currently, it can't be sideloaded on the web, Mac, or iPad.

Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)

Use the process described in Sideload with a system prompt, bash shell, or terminal.

Sideload with the Teams Toolkit

1. First, make sure Office desktop application that you want to sideload into is closed.

2. In Visual Studio Code, open Teams Toolkit.

3. Required for Outlook only: in the ACCOUNTS section, verify that you're signed into Microsoft 365.

4. Select View | Run in Visual Studio Code. In the RUN AND DEBUG dropdown menu, select one of these options as appropriate for your add-in.

   • Excel Desktop (Edge Chromium)
   • Outlook Desktop (Edge Chromium)
   • PowerPoint Desktop (Edge Chromium)
   • Word Desktop (Edge Chromium)

5. Press F5. The project builds and a Node dev-server window opens. This process may take a couple of minutes and then the desktop version of the Office application that you selected opens. You can now work with your add-in. For an Outlook add-in, be sure you're working in the Inbox of your Microsoft 365 account identity.

6. To stop debugging and uninstall the add-in, select Run | Stop Debugging in Visual Studio Code. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

Sideload with a system prompt, bash shell, or terminal

1. First, make sure the Office desktop application that you want to sideload into is closed.
2. Open a system prompt, bash shell, or the Visual Studio Code TERMINAL, and navigate to the root of the project.
3. The command to sideload the add-in depends on when the project was created. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run npm run start:desktop; otherwise, run npm run start. The project builds and a Node dev-server window opens. This process may take a couple of minutes then the Office host application (Excel, Outlook, PowerPoint, or Word) desktop opens.
4. You can now work with your add-in.
5. When you're done working with your add-in, make sure to run the command npm run stop. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

Sideload other NodeJS and npm projects

There are two tools you can use to sideload.

Sideload with the Office-Addin-Debugging tool

1. To sideload the add-in, run the following command. This command puts the unified manifest and the two icon image files that are referenced in the manifest's "icons" property into a zip file and sideloads it to the Office application. It also starts a server in a separate NodeJS window to host the add-in files on localhost. For more details about this command, see Office-Addin-Debugging.

   npx office-addin-debugging start <relative-path-to-unified-manifest> desktop
   

2. When you use office-addin-debugging to start an add-in, always stop the session with the following command. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in.

   npx office-addin-debugging stop <relative-path-to-unified-manifest>
   

Sideload with the Teams Toolkit CLI (command-line interface)

1. Manually create a zip package using the following steps.

   1. Open the unified manifest and scroll to the "icons" property. Note the relative path of the two image files.
   2. Use any zip utility to create a zip file that contains the unified manifest and the two image files. The image files must have the same relative path in the zip file as they do in the project. For example, if the relative path is "assets/icon-64.png" and "assets/icon-128.png", then you must include the "assets" folder with the two files in the zip package.
   3. If the folder contains other files, such as image files used in the Office ribbon, remove these from the zip package. It should have only the two image files specified in the "icons" property (in addition to the manifest in the root of the zip package).

2. In the root of the project, open a command prompt or bash shell and run the following command to install the Teams Toolkit CLI.

   npm install -g @microsoft/teamsapp-cli
   

3. Run the following command to sideload the add-in.

   teamsapp install --file-path <relative-path-to-zip-file>
   

   Important

   This command returns some information about the add-in including an autogenerated title ID as shown in the following example.

   

   You'll need this title ID to end the sideloading and debugging session, so save it. We recommend that you put it in a text file in the root of the project and name the file TitleID.txt.

4. When you use the Teams Toolkit CLI to start an add-in, always stop the session with the following command. Closing the server window doesn't reliably stop the server and closing the Office application doesn't reliably cause Office to unacquire the add-in. Replace "{title ID}" with the title ID of the add-in including the "U_" prefix; for example, U_90d141c6-cf4f-40ee-b714-9df9ea593f39.

   teamsapp uninstall --mode title-id --title-id {title ID} --interactive false
   

   Important

   The documentation for the uninstall command describes a way to use the add-in's manifest ID instead of the title ID. Due to a bug in an API that the CLI calls, this option doesn't currently work. You must use the uninstall command given above and you must include the --interactive false option.