---
title: Install Optimizely apps (add-ons)
slug: cms-13/docs/install-optimizely-apps
docTags: 
createdAt: 2026-07-30T20:22:02.890Z
---

Optimizely Content Management System (CMS 13) uses [NuGet](https://nuget.optimizely.com/) to handle app packages (sometimes called add-ons) in a standard format. Install apps from Visual Studio or through the add-on UI.

:::hint{type="info"}
**Note**
For Azure environments, install app modules only through Visual Studio (not from the add-on UI).
:::

## Configure installation options

Control whether you install CMS 13 apps through Visual Studio or the UI. Specify the installation mode in your configuration file.

`<episerver.packaging installationMode="MODE">`

Set `installationMode` to `Code` (Visual Studio) or `UI`. Use one method consistently for installing, upgrading, and uninstalling add-ons. Mixing methods causes unexpected behavior. For example, an app installed from Visual Studio displays in the add-on UI, but disable and uninstall operations are unavailable.

## Install apps from Visual Studio

Prepare your environment for Visual Studio-based app installation.

1. Set `installationMode` to `Code`: `<episerver.packaging installationMode="Code">`.
2. Run the `Convert-EPiAddons` cmdlet in the Package Manager Console if you previously set `installationMode` to `UI`. The cmdlet converts UI-installed apps to Visual Studio format.
3. Add `https://nuget.episerver.com/feed/packages.svc/` as a NuGet source.
4. Install and upgrade apps through Visual Studio.

### `Repository.config`

The `modules/_protected` folder contains a `repository.config` file created during add-on system initialization. If the server is hardened, IIS lacks write access to the `_protected` folder. The site fails to launch with an `Access denied` message. Grant `IIS_IUSRS` modify rights to the `_protected` folder to resolve this issue.

Each web server in a load-balanced environment has its own `repository.config` file with a unique GUID. The app system executes custom code when an app is installed, updated, or uninstalled. The system uses the GUID to verify that custom code runs on all servers. Copy the generated `repository.config` file for each machine as part of multi-site deployments.

Do not commit `repository.config` to source control because each server requires a unique GUID.

## Install apps from the UI

The add-on UI lets you install apps without access to Visual Studio. To install add-on packages, you must be a member of the **PackagingAdmins** user group and have access to the Optimizely UI.

Set `installationMode` to `UI`:

```xml
<episerver.packaging installationMode="UI">
```

## Install app packages from the central repository

The central repository provides access to all available apps for CMS 13.

In CMS 13, select **Add-ons** in the global menu. The installation process works as follows:

1. Add packages to a temporary repository.
2. Resolve dependencies and install the packages into the application from the temporary repository, combined with other repositories.
3. Validate uploaded files and selected add-ons as valid NuGet packages marked with the `EPiServerModulePackage` or `EPiServerPublicModulePackage` module tags.
4. Instantiate the package for any number of applications after installing it in the repository.

### Change the location of the temporary repository

The following package source repositories are available:

- The central repository
- The temporary repository
- The site local repository

The temporary repository uses virtual packages to resolve dependencies before installation, representing available assemblies on the site and the local repository. By default, the operating system designates the location of the temporary repository directory. To change the directory, update the `packagesTemporaryFolder` attribute in the `episerver.packaging` element:

```xml
<episerver.packaging packagesTemporaryFolder="...">
```

### Change the location of the local repository

CMS configures the site directory, `C:\\EPiServer\<SiteName>\\wwwroot\\modules`, with correct access rights when you install Optimizely Framework from Deployment Center. Installed packages are added to the local repository. To change the directory, update the `repositoryPath` attribute on the `episerver.packaging` element:

```xml
<episerver.packaging repositoryPath="C:\EPiServer\Sites\MySite\App_Data\Packages">
```

:::hint{type="info"}
**Note**
Ensure the web application has write access rights for the specified directory.
:::

### Add repositories to the configuration

Add repositories to the configuration as shown in the following example:

```xml
<episerver.packaging>
  <packageRepositories>
    <add name="Gallery" url="\\server\Your\Packages\Folder" />
  </packageRepositories>
</episerver.packaging>
```

:::hint{type="info"}
**Note**
Installed apps are registered in the file in the site root. Supported files are copied to the corresponding app folder in the `~/modules/` directory. For the `episerver.packaging` element description, go to [episerver.packaging (Legacy)](docId\:kLk_YZEIus3gv5Qkx0YCu) (CMS 11).
:::

### Copy app assemblies to the probing path directory

App assemblies compatible with the current framework version are copied to the probing path directory at `dirmodulesbin` under `C:/EPiServer/<SiteName>/wwwroot/`. The probing path directory must be available at this location. Define it in the `probingPath` attribute in the `configuration/episerver.framework/scanAssembly` element. Configure the same path in the `privatePath` attribute of the probing element.

`EPiServerFramework.config`

```xml
<episerver.framework>
<scanAssembly forceBinFolderScan="true" probingPath="modulesbin" />
```

`web.config`

```xml
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
<probing privatePath="modulesbin" />
```

### Complete the installation

After you install app packages, the results display whether you must restart the site (if ASP.NET does not automatically restart it). A site restart is required to load and scan assemblies and initialize installed apps.

## Update an app

The **Updates** tab shows available updates for installed apps. When you upgrade an app, the old version is uninstalled, and the replacement is installed. The update process also updates related apps (dependencies and dependents).

## Disable an app

After an upgrade, some apps may become incompatible and prevent the site from starting. Disable incompatible apps to restore access to the UI.

Disable an app (such as `EPiServer.Cms.AddOns.Blocks` in the following example) in the configuration file:

```xml
<episerver.framework>
	<scanAssembly>
		<add assembly="*" />
		<remove assembly="EPiServer.Cms.AddOns.Blocks" />
	</scanAssembly>
	<!-- other settings -->
</episerver.framework>
```

## Uninstall an app

The **Installed** tab shows installed apps. Uninstall apps from this tab, except for system apps (such as the management system app, which supports upgrade only). App files and the corresponding Shell module folder are removed during uninstallation, and assemblies are deleted from the probing path directory. The site restarts to complete the uninstallation and unload app assemblies from the application domain.