Zip File
A Zip File in Salesforce metadata deployment is a compressed archive (.zip) that bundles a set of metadata components (Apex classes, Lightning Web Components, custom objects, layouts, profiles, per…
Definition
A Zip File in Salesforce metadata deployment is a compressed archive (.zip) that bundles a set of metadata components (Apex classes, Lightning Web Components, custom objects, layouts, profiles, permission sets) in their canonical directory structure and ships them between orgs through the Metadata API. The Zip File is the wire format the platform uses for both deploy and retrieve operations. A retrieve pulls metadata out of an org as a Zip File; a deploy unpacks a Zip File into a target org.
The Zip File approach predates the modern Salesforce DX source format and is still the underlying transport for every metadata operation. Tools like the Salesforce CLI, Workbench, Force.com Migration Tool (ANT), and most third-party deployment products (Copado, Gearset, AutoRABIT) build the Zip Files behind the scenes when deploying changes. Understanding the Zip File shape matters when troubleshooting deployment failures, auditing what got moved between orgs, or building custom deployment automation.
Salesforce metadata Zip Files: structure, deployment lifecycle, and troubleshooting
What a metadata Zip File actually contains
A Salesforce metadata Zip File is structured around a package.xml manifest at the root and one folder per metadata type containing the actual files. A typical Zip File contains: package.xml (the manifest listing every metadata component included), classes/ (Apex classes as .cls files with paired .cls-meta.xml), triggers/, lwc/ (Lightning Web Components as folders containing HTML, JS, CSS, and an XML metadata file), objects/ (custom objects as .object XML files), layouts/, profiles/, permissionsets/, flows/, and others. Each file inside the Zip has a specific role; the platform reads the manifest first to know what to expect, then processes each file against the target org. The shape is deterministic, which makes the Zip File suitable for both manual review and automated deployment.
package.xml and the deployment manifest
The package.xml manifest is the central piece of any metadata Zip File. It is an XML document that lists every metadata component the Zip File contains, organized by metadata type. Each type lists members (specific named components) or a wildcard (*) for all components of that type. The manifest also specifies the API version, which determines which Salesforce release behavior the deployment targets. Missing a component from the manifest means it does not deploy, even if its file is present in the Zip. Including a component in the manifest but missing its file means the deploy fails with a missing-file error. Mature deployment pipelines generate the manifest dynamically from source-control diffs so only changed components ship.
Deploy operations and the deployment lifecycle
When the Salesforce CLI runs sf project deploy start (or the older sfdx force:mdapi:deploy), the tool packages the source into a Zip File, uploads it to the target org through the Metadata API, and triggers the deployment job. The platform unpacks the Zip in the target org, validates each component against the target schema, runs the deploy in a transaction, and either commits the change or rolls back on error. Deployments can be validate-only (compile and dry-run without committing) or full (commit the changes). Apex test execution is configurable per deploy: no tests, local tests only, all tests, or specific named tests. The deployment job runs asynchronously; the CLI polls for status until the job completes.
Retrieve operations and metadata extraction
Retrieve is the inverse of deploy. The CLI runs sf project retrieve start (or the older sfdx force:mdapi:retrieve) with a package.xml manifest specifying which metadata to pull. The platform queries the source org, packages the requested metadata into a Zip File, and returns it. Retrieve is the standard way to extract metadata from an org into a Salesforce DX source format project (the CLI converts between metadata API format and DX source format automatically). Retrieve is also how many deployment tools take an initial snapshot of an org before they start tracking changes. The retrieve operation respects the user permissions; metadata the retrieving user cannot read does not get included in the Zip.
Metadata API format vs Salesforce DX source format
Two file formats coexist. The Metadata API format is the older one, structured around the Zip File for transport: each Apex class is a .cls file with a single .cls-meta.xml file in the same folder, custom objects are bundled into a single .object XML file. The Salesforce DX source format is newer, structured for version control: custom objects break out into one file per field, one file per validation rule, one file per record type. The Salesforce CLI converts between the two formats. Source format is the recommended structure for the working directory in Git; metadata API format is the structure inside the Zip File that ships during deploy. Most modern projects work in source format and let the CLI handle the conversion.
Troubleshooting deployment failures from the Zip File
When a deploy fails, the platform returns an error log that lists which components failed and why. The log references components by their type and member name (ApexClass:MyController, CustomObject:Custom_Object__c). To diagnose, open the Zip File, navigate to the failing component file, and inspect the metadata XML. Common failure modes: API version mismatch (the source API version is newer than what the target org supports), missing dependencies (the deploy includes a Field that references a Custom Object not in the deploy), profile XML conflicts (a profile references a field that does not exist in the target), Apex test failures (deploy fails if test coverage drops below 75 percent). Reading the Zip File and the error log together is the standard troubleshooting workflow.
Building, deploying, and troubleshooting Salesforce metadata Zip Files
Working with metadata Zip Files is a foundational deployment skill. The four-step routine covers: build a package.xml manifest for the components you want to deploy, retrieve or generate the Zip File, deploy it to the target org through the Salesforce CLI, and troubleshoot any failures by inspecting the Zip and the error log. Modern tools (Salesforce DX, Copado, Gearset) hide most of the mechanics, but the underlying Zip File still drives every operation. Understanding the format helps when automation breaks or when custom deployments are required.
- Build the package.xml manifest
Write a package.xml file that lists every metadata component your deployment includes. Group components by type; under each type, list the specific members (named components) or use the wildcard (*) for everything. Set the API version to the target Salesforce release. For deployments derived from source control, generate the manifest dynamically from the Git diff so only changed components ship. Tools like Salesforce CLI sf project deploy start with --source-dir do this automatically; manual deployments need explicit manifests. Validate the manifest XML against the metadata schema before deploying.
- Generate the Zip File
From Salesforce DX source, run sf project convert source to mdapi to produce a metadata API format Zip File. Alternatively, retrieve from a source org with sf project retrieve start using your package.xml. The output is a directory containing the package.xml at the root and one subfolder per metadata type with the component files inside. Compress this directory into a Zip File for tools that need the wire format directly. Most modern tools work with the directory and Zip internally; manual workflows compress the directory by hand.
- Deploy the Zip File to the target org
From the Salesforce CLI, run sf project deploy start with --metadata-dir and --target-org parameters. The CLI uploads the Zip to the target org and starts the deploy job. Watch the deploy progress in the CLI or in Setup, Deployment Status. For validate-only deploys, add --dry-run. For Apex test execution, add --test-level RunLocalTests or --test-level RunSpecifiedTests --tests. Capture the deploy id from the CLI output; you can resume monitoring or cancel the deploy by id later. For deployment from a CI pipeline, parameterize the credentials and the target org alias.
- Troubleshoot failures by inspecting the Zip and the error log
On any deploy failure, the CLI returns an error log listing failed components and the reason for each. Open the package.xml and confirm the component is listed. Open the corresponding file in the Zip and inspect the metadata XML for obvious issues: API version mismatch, missing field references, profile XML conflicts. Common fixes: bump the API version, add missing dependencies to the package, regenerate the profile XML against the target org schema, fix the Apex test that dropped coverage below 75 percent. Re-deploy after each fix and confirm the failure is resolved before moving on.
- Missing files in the Zip but listed in package.xml cause deploy failure. Conversely, extra files not in package.xml are silently ignored. Always regenerate the manifest before packaging.
- Profile XML can be huge and notoriously hard to diff. Use Permission Sets for everything you can and use tools like Sfpowerkit to clean Profile XML on retrieve.
- Apex deploy requires 75 percent test coverage org-wide post-deploy. A deploy that drops coverage below the threshold fails entirely, even if the changed code itself is fully covered.
- Validate-only deploys do not write changes but still consume API quota and platform compute. Run them strategically; do not validate from CI on every single commit if quota is constrained.
- Metadata API format and Salesforce DX source format are different. Mixing them in the same directory produces deployment errors. The Salesforce CLI converts between them; do not try to mix manually.
Trust & references
Straight from the source - Salesforce's reference material on Zip File.
- Metadata API Developer GuideSalesforce Developer Docs
- File-Based Metadata DeploymentSalesforce Developer Docs
- Salesforce CLI ReferenceSalesforce Developer Docs
Hands-on resources to go deeper on Zip 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 is a Zip File in metadata context?
Q2. What tools use zip files?
Q3. What's inside the zip?
Discussion
Loading discussion…