Skip to main content
Pre-built plugin installation is being rolled out gradually and might not be available in your instance yet. Look for the Custom Plugins tab under Admin → Plugin Settings. If the tab is not present, follow the previous installer instructions. See Switching to pre-built plugins for rollout details and help moving existing plugins.
Portal installs supported public Backstage packages as pre-built plugins. Spotify prepares these packages in advance, and Portal downloads and activates them when you install them. Plugins developed or modified by your organization use a different workflow. See Publish and install custom plugins to publish and install them.

​
How installation works

Spotify discovers supported plugin releases from the public npm registry, checks their package metadata and compatibility, installs their dependencies in an isolated build environment, and prepares the artifacts that Portal needs. Successfully prepared releases are then made available to Portal instances. When you install a package, Portal:
  1. Resolves the requested version. If you omit a version, Portal uses the latest stable release.
  2. Finds related packages, such as the frontend and backend packages that make up the same plugin.
  3. Shows the exact package versions and feature types for review.
  4. Downloads and activates the prepared artifacts after you confirm the installation.
Plugin configuration and runtime behavior remain specific to the plugin. Pre-building a plugin does not remove the need to follow its setup instructions.
If this is your first time installing a plugin, you will be asked to accept a consent disclaimer acknowledging that installed packages have access to Portal data and configuration. This prompt only appears once.
The Explore tab features a curated collection of community and partner plugins. Go to Admin → Plugin Settings → Explore, find the plugin you want to add, and select Install.
The Explore tab showing a curated collection of community and partner plugins
Review the packages Portal resolved for the plugin, accept the plugin installation consent if prompted, and select Install.

​
Install a plugin by package name

Use this method for a supported public plugin that is not listed in Explore.
  1. Go to Admin → Plugin Settings and select Add plugin.
  2. Enter the npm package name. Add each known frontend, backend, or module package on a separate line; Portal can also add related packages during analysis.
  3. To request a specific stable version, append it to the package name, for example @backstage/plugin-example@1.2.3. If you omit the version, Portal resolves latest. See Plugin Versioning for supported versions.
  4. Select Analyze.
  5. Review the resolved versions, related packages, roles, and any messages. Remove packages you do not want to install.
  6. If prompted, accept the plugin installation consent, then select Install.
  7. Configure and test the plugin by following its documentation.
The installation dialog showing the resolved frontend, backend, and module packages for the PagerDuty plugin
Start with the package names listed in the plugin’s own installation guide. Portal’s analysis can discover related packages, but it cannot infer optional modules or organization-specific configuration.

​
If a plugin is not available

Portal only offers releases that it has discovered and prepared successfully. The installation dialog shows package-specific information when a package or version cannot be used.
  • Confirm the package name and version against the plugin’s npm page and documentation.
  • Read the error details for a compatibility, metadata, dependency, or build problem. The issue is often in that plugin release rather than in your Portal instance.
  • Check whether a newer plugin release resolves the problem.
  • If your organization maintains the package, publish it as a custom plugin instead.
  • If the message does not provide enough information, contact Customer Support. Customer Support can inspect the preparation logs for more detail. Include the package name, requested version, Portal instance, and error message in your request.
For experimental or prerelease code, use the custom plugin publishing workflow.

​
Using the previous installer

These instructions apply if your instance does not yet have the Custom Plugins tab, or Portal directs you to the previous installer. See Switching to pre-built plugins for details.
  1. From Plugin Settings, select Add plugin.
The Add plugin button on the Plugin Settings page
  1. Enter the npm package name. If the plugin has multiple packages, add each package name on a separate line.
If this is your first time installing a plugin, you will be asked to accept a consent disclaimer acknowledging that installed packages have access to Portal data and configuration. This prompt only appears once.
  1. Select Install to start the build.
  2. Monitor the operation in the build dialog. See Build Progress for details.
  3. When the build completes, select Finish, then configure and test the plugin.
Installation complete with Finish button
To install a specific version, append @ followed by the version number to the package name, for example @backstage/plugin-example@1.2.3. If no version is specified, Portal installs the latest stable version. See Plugin Versioning for more details.