InstalledPackage Metadata Type in SFDX

Architectural Overview#

The InstalledPackage metadata type represents an installed 1GP (First-Generation Managed Package) or 2GP (Second-Generation Managed Package) within a Salesforce environment. In enterprise architectures, external applications, AppExchange solutions, and modular internal packages (such as common logging frameworks or billing engines) must be installed and upgraded systematically across the environment pipeline.

Architecturally, InstalledPackage provides a declarative, version-controlled mechanism to trigger package installations and upgrades via Metadata API deployments. Rather than relying on manual installation URLs, enterprise CI/CD workflows leverage InstalledPackage manifests to enforce exact package version alignment between scratch orgs, sandboxes, and production environments.

Directory and File Conventions#

In Salesforce DX source format, InstalledPackage files are stored in the installedPackages directory with the filename corresponding to the package namespace:

Key Metadata Fields#

The XML definition of InstalledPackage defines version parameters and installation behavior:

Declarative XML and Package Manifest Examples#

Source XML (sf_chttr_apps.installedPackage-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<InstalledPackage xmlns="http://soap.sforce.com/2006/04/metadata">
    <versionNumber>1.17</versionNumber>
    <activateRSS>false</activateRSS>
    <securityType>AllUsers</securityType>
</InstalledPackage>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>sf_chttr_apps</members>
        <name>InstalledPackage</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

To retrieve all installed packages from an existing organization:

# Retrieve all installed packages
sf project retrieve start --metadata InstalledPackage

# Retrieve a specific package by namespace
sf project retrieve start --metadata InstalledPackage:sf_chttr_apps

To install or upgrade an installed package via CLI deployment:

# Deploy InstalledPackage to install in target sandbox
sf project deploy start \
  --metadata InstalledPackage:sf_chttr_apps \
  --target-org uat \
  --wait 20

You can also inspect installed packages using SOQL via the Tooling API:

# Query installed packages via Tooling API
sf data query \
  --query "SELECT Id, SubscriberPackageId, SubscriberPackage.NamespacePrefix, SubscriberPackageVersion.Name, SubscriberPackageVersion.MajorVersion, SubscriberPackageVersion.MinorVersion FROM InstalledSubscriberPackage" \
  --target-org uat \
  --use-tooling-api

Senior Architect Deployment Best Practices and Gotchas#

CI/CD Deployment Sequencing#

Managed packages must always be deployed and compiled before deploying any custom code, layouts, or flows that reference namespaced objects (namespace__CustomField__c):

1. Step 1: Install Managed Packages via sf package install or InstalledPackage metadata deployment.
2. Step 2: Apply Package Licenses and Permission Set Assignments.
3. Step 3: Deploy core project source code referencing the package components.

Downgrade Restrictions#

Salesforce prohibits downgrading managed package versions in persistent environments (production and sandboxes). If your repository’s InstalledPackage XML references an older version than what is currently installed in the target org, deployment will fail with a version downgrade error.

Frequently asked questions

What is the InstalledPackage metadata type in Salesforce?

It represents an installed first-generation or second-generation managed package in an org, defining version number and activation options.

Can deploying an InstalledPackage file install a package into an org?

Yes, deploying an InstalledPackage XML file via Metadata API triggers installation or upgrade of that package version in the target org.

Where are InstalledPackage files stored in an SFDX project?

They are stored in force-app/main/default/installedPackages with the file suffix installedPackage-meta.xml.

How do architects specify package passwords in InstalledPackage metadata?

The password tag can be populated in the XML file or supplied via CLI parameters during automated package installation commands.