Manifest File
A manifest file in Salesforce is an XML file, usually named package.xml, that lists the metadata components you want to retrieve from or deploy to an org. The Metadata API reads the manifest as a r…
Definition
A manifest file in Salesforce is an XML file, usually named package.xml, that lists the metadata components you want to retrieve from or deploy to an org. The Metadata API reads the manifest as a request specification. It declares which metadata types are involved and which named members within each type are part of the operation. The Salesforce CLI commands sf project retrieve start and sf project deploy start both accept a manifest to scope exactly what moves between your local project and an org.
A second manifest, destructiveChanges.xml, uses the same format to list components you want to delete. Together the two files describe a complete deployment: what to add or update, and what to remove. Manifests are the backbone of metadata work outside source-tracked environments. Production deployments, packaging builds, and most CI/CD pipelines all reference a manifest to control precisely which components get touched.
How a package.xml manifest is put together
The shape of the XML
A package.xml manifest has a single Package root element. Inside it sit one or more types blocks, and a single version element at the bottom. Each types block describes one metadata type. It contains a name element holding the type's API name, such as ApexClass, CustomObject, or Flow, plus one or more members elements naming the specific components. A members value of TaxCalculator inside an ApexClass block targets exactly that one class. The version element holds the API version the operation runs against, written as a number like 62.0. That version tells Salesforce which metadata types exist and how to interpret each component. The XML is plain text, so you can read it, diff it in git, and edit it by hand when you need to. Order inside the file does not change behavior, but teams often keep the types blocks alphabetical for readability. A malformed manifest, such as a name that is not a real metadata type, fails fast with a clear error rather than silently skipping components. That predictability is a big part of why the format has lasted.
Wildcards versus explicit member lists
A members value can be a literal component name or the wildcard asterisk. The wildcard means every component of that type in the org. So a CustomObject block with a single asterisk member retrieves all custom objects at once. Wildcards are convenient for pulling a full slice of an org into a fresh project, or for refreshing a sandbox. They are riskier for deployments, because a wildcard can sweep in components you did not mean to move, including ones another team owns. For production work, most teams write explicit member lists so the payload contains only the components under review. Note that the wildcard does not cover every metadata type. Some types, such as standard objects and certain settings, are not returned by an asterisk and must be named explicitly. The Metadata API documentation flags which types support the wildcard. A common pattern is a wildcard manifest for the initial retrieve, then a hand-trimmed manifest with named members for the actual deploy.
destructiveChanges.xml and deletions
A package.xml manifest only adds or updates metadata. It never deletes anything. To remove components from a target org you pair it with a destructiveChanges.xml file. That file uses the exact same XML format, with types, name, and members elements, but every component it lists gets deleted instead of created. You can also use destructiveChangesPre.xml and destructiveChangesPost.xml to control whether deletions run before or after the additions in package.xml. When you deploy, all of these files travel together in one zip alongside the source folder. Salesforce processes the additions and updates from package.xml first, then applies the deletions. This pairing is how teams handle rename and replace work, where an old field or class goes away as a new one arrives. One subtlety: a destructive deployment still needs a package.xml present, even an effectively empty one with just a version element, because the API expects it as the entry point for the package.
How the Salesforce CLI uses a manifest
The Salesforce CLI reads a manifest through the -x flag, which is shorthand for --manifest. Running sf project retrieve start -x manifest/package.xml pulls every component the manifest names into your local project. Running sf project deploy start -x manifest/package.xml sends those components to the target org. You can layer other flags on top, such as --target-org to pick the destination and --test-level to control which Apex tests run during a production deploy. The CLI can also build a manifest for you, so you rarely type the XML from scratch. sf project generate manifest reads a source directory or queries an org and writes a package.xml that matches. That generated file is a starting point you can trim. The CLI replaced the older Ant Migration Tool and the force:source and force:mdapi commands, but the manifest format stayed the same. A package.xml written years ago for Ant still works with today's sf commands, which is why so much existing tooling carries forward unchanged.
Manifests inside CI/CD pipelines
Continuous delivery pipelines lean on manifests to decide what each deployment contains. A typical pipeline compares two git branches, finds the components that changed, and builds a package.xml listing exactly those. It then calls sf project deploy start against that manifest to push the delta to the next environment. Salesforce DevOps Center follows this idea with a point and click interface, tracking changes as work items and assembling the deployment for you behind the scenes. Third party platforms such as Gearset, Copado, and AutoRabit do the same diff and build step, often adding test orchestration and approval gates on top. The shared thread is that the manifest stays the unit of control. Even when a tool hides the XML, a package.xml is being generated and deployed underneath. Understanding the format pays off when a pipeline misbehaves, because the fastest way to see what a deployment actually carried is to read the generated manifest. It is the receipt for every component that moved.
How a manifest differs from a change set
A change set is the declarative cousin of a manifest. An admin opens an outbound change set in Setup, picks components from a list, and Salesforce assembles the deployment payload internally. No XML is written or seen. Change sets are friendly for admins and need no command line, but they are slower to build by hand, cannot be version controlled, and only move between connected orgs in the same Salesforce instance family. A manifest is the opposite trade. It demands a little XML literacy, yet it lives in git, deploys through automation, and works against any org the CLI can authenticate to. Because the manifest is just text, you can review it in a pull request, reuse it across environments, and store it as a record of what a release contained. Most admin led teams start with change sets and move to manifests once deployments grow frequent enough that a repeatable, reviewable file beats clicking through the same component list every release.
Matching the manifest version to the org
The version element at the bottom of a package.xml is easy to overlook and a frequent source of deploy failures. It names the Metadata API version the operation runs under, such as 62.0 for a recent release. That number controls which metadata types Salesforce recognizes and how it parses each component's XML. If a manifest sets a version higher than the target org supports, the deploy can fail because the org does not know about types or attributes introduced in that later release. If the version is much older than the components were authored against, newer fields on those components may be dropped or rejected. The safe practice is to set the manifest version to the org's current API version, or one the org clearly supports. The CLI's generate manifest command stamps a sensible version for you. When you copy a manifest between orgs on different release schedules, checking that one version line first saves a confusing round of failed deployments.
Generate a package.xml manifest with the Salesforce CLI
You rarely hand-type a manifest from a blank file. The Salesforce CLI generates one from your source or from an org, and you trim it. Here is how to produce a package.xml you can deploy with.
- Open a project and pick a source
Work inside a Salesforce DX project so the CLI knows your folder layout. Decide whether the manifest should reflect local files in force-app or live metadata in a connected org.
- Generate the manifest
From local source, run sf project generate manifest --source-dir force-app --name package. To capture an org instead, add --from-org with the org alias. The CLI writes a package.xml under the manifest folder.
- Trim the types and members
Open the generated package.xml and remove any types blocks you do not want in this deployment. Replace broad wildcards with explicit member names for a production payload, leaving only the components under review.
- Set the version line
Check the version element near the bottom. Set it to the target org's current API version so the deploy does not fail on an unsupported metadata type.
- Deploy or retrieve with it
Run sf project deploy start -x manifest/package.xml --target-org your-alias to deploy, or sf project retrieve start -x manifest/package.xml to pull the listed components down.
The single XML root element that wraps the whole manifest. Every other element nests inside it.
The API name of a metadata type inside a types block, such as ApexClass or CustomObject. Must match a real Metadata API type.
The specific component to include, or the asterisk wildcard for all components of that type. One types block can hold many members.
The Metadata API version the operation runs under, written as a number like 62.0. Should match a version the target org supports.
- A package.xml only adds and updates. Use a separate destructiveChanges.xml to delete components.
- The asterisk wildcard does not cover every metadata type. Standard objects and some settings must be named explicitly.
- A version higher than the target org supports causes deploy failures on unrecognized types. Match it to the org.
- Generated manifests can include components you did not intend. Always trim the file before a production deploy.
Prefer this walkthrough as its own page? How to Manifest File in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Manifest File.
Hands-on resources to go deeper on Manifest File.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does a Manifest File like package.xml specify for a metadata operation?
Q2. Which companion manifest works alongside package.xml to remove components during a deployment?
Q3. When are Manifest Files most necessary in a Salesforce DX deployment workflow?
Discussion
Loading discussion…