Namespace Prefix
A Namespace Prefix in Salesforce is the unique alphanumeric identifier (1 to 15 characters, starting with a letter) registered for a managed package that prepends to every component shipped in that package.
Definition
A Namespace Prefix in Salesforce is the unique alphanumeric identifier (1 to 15 characters, starting with a letter) registered for a managed package that prepends to every component shipped in that package. Every custom object, custom field, Apex class, Lightning component, page layout, and other metadata element from a managed package carries the namespace prefix in its API name, separated from the local name by a double underscore. The prefix ensures that components from different packages never collide with each other or with customer-org-local components, even when they share the same local name.
For example, a custom object named ProjectTask in a package with namespace prefix acme appears in subscriber orgs as acme__ProjectTask__c. The same package's Apex class named ProjectHelper appears as acme.ProjectHelper. Customer-org-local custom fields on the same object remain in the org's default namespace (no prefix), so an admin who adds a field named Region__c to an installed namespace package's object sees it as Region__c (not acme__Region__c). This separation between vendor-shipped and customer-added components is what makes managed packages safe to upgrade without breaking customer customizations.
How namespace prefixes work in practice
Registration and uniqueness
Namespace prefixes are registered through the Salesforce DX CLI (sf org namespace) or the legacy Developer Console flow against a Dev Hub org. Each prefix must be globally unique across Salesforce; once registered, no other developer can claim the same prefix. The choice of prefix is permanent for the package's lifetime; changing it after a package has been distributed requires creating a new package and migrating subscribers. ISVs typically choose prefixes that match their brand or product line (acme, finco, healthx). Internal teams creating unlocked packages for enterprise distribution may use shorter, internal-meaningful prefixes (intops, sharedlib).
Local versus namespaced component names
Inside the package's source code, components are referenced by their local name without the prefix. Apex code in a package with namespace acme would reference its own custom object as ProjectTask__c, not acme__ProjectTask__c. The platform automatically resolves the local name to the namespaced version at runtime. References to components in other packages or in the customer org's default namespace require the explicit prefix: acme__OtherObject__c when reading another package's object, or just MyField__c (no prefix) when reading a customer-org-local field. This local-name convenience inside the package keeps the source code readable while preserving the namespace-uniqueness benefit at the platform level.
Namespace and dynamic Apex
Apex code that uses dynamic features (Schema.getGlobalDescribe, Database.query with string SOQL, Type.forName) sometimes needs to reference component names by string. When the code is in a namespace, the strings should include the namespace prefix for cross-namespace references. Failing to namespace these string references is one of the most common bugs in managed-package code, because it works in the developer's namespaced sandbox but fails when the same code runs in a customer org against components in different namespaces. The platform provides utilities to determine the current namespace at runtime (UserInfo.getOrganizationId, package-aware methods) but the developer must use them correctly.
Customer-org customizations on namespaced packages
Subscriber customers can add their own components to a namespaced package's objects. A custom field added by the subscriber on the namespaced object lives in the subscriber's default namespace (no prefix), so the same package object can have a mix of vendor-shipped namespaced fields and customer-added unprefixed fields. The package vendor cannot delete or modify the customer-added fields during package upgrade; the namespace separation enforces this safety. This is one of the most valuable properties of managed packages: customers can customize without fear of losing their additions to the next vendor upgrade.
Querying and reporting across namespaces
When admins build reports or write SOQL across namespaced components, they specify the full namespaced API name: acme__ProjectTask__c.acme__Region__c. The Salesforce UI typically shows the namespace and the local name separately in field labels (Region (acme)), which helps admins distinguish vendor-shipped fields from customer-org-local fields with the same local label. Report types and dashboards work across namespace boundaries transparently, so customers can build reports combining vendor data with their own customizations without any namespace-aware coding.
Namespace prefixes for unlocked packages
Unlocked packages can also have namespace prefixes, though it is optional. Unlocked packages without a namespace prefix install into the subscriber org's default namespace, which is fine for internal enterprise distribution but loses the upgrade-safety benefits of namespacing. Unlocked packages with a namespace prefix get the same benefits as managed packages: components are isolated, customer-org customizations are safe, and package upgrades do not collide with local changes. Enterprises distributing multiple unlocked packages to multiple business unit orgs typically use namespace prefixes to keep the components separated and predictable.
Common namespace-related pitfalls
Three issues recur with namespace handling. Hardcoded namespace references in Apex break when the same code is run in different orgs (the namespace differs between the development org and the customer org). Dynamic SOQL or Apex code that does not prepend the namespace prefix to component names fails for cross-package references. Components named generically (Account__c, Contact__c) within a namespace conflict with standard Salesforce object names when the namespace context is ambiguous; clear naming conventions avoid this. Each of these pitfalls is documented in the Salesforce developer guide, but the patterns recur in code review across packages and require ongoing attention.
Namespace evolution and the long-term picture
For a successful ISV package, the namespace prefix becomes part of the brand: customers refer to acme objects, partners write integrations against acme APIs, and the prefix appears in every customer-facing documentation page. This permanence is both a benefit (consistent identity across the customer base) and a constraint (the prefix is part of every API contract and cannot evolve). Some ISVs have considered rebranding to a new prefix as part of a major product transition; in every case, the consensus is that the migration cost across the installed base is prohibitive. Instead, the original prefix continues to be used even as the brand evolves, with marketing materials sometimes referencing the original technical prefix as a historical curiosity. For internal enterprise teams distributing unlocked packages, the same principle applies: choose a prefix that will age well across the company's evolution rather than tying the prefix too tightly to a specific project name or team that may change over time. Twenty years from now, the prefix you choose today will still be in API names and Apex code throughout your installed base.
Register and use a namespace prefix
Registering a namespace prefix is a one-time setup for a package, but using it correctly is an ongoing development concern. The workflow below covers the standard sequence for a new ISV or enterprise team setting up a namespaced package.
- Choose and register the namespace prefix
Decide on a namespace prefix that is meaningful for the brand or product (1 to 15 alphanumeric characters, starting with a letter). Check availability through the Salesforce DX CLI (sf org namespace list or the Developer Console namespace registration UI). Register the prefix in the Dev Hub org. The registration is immediate and permanent: the prefix is yours globally across Salesforce. Document the prefix choice in the project README so all developers on the team use it consistently.
- Configure the Salesforce DX project
Update the project's sfdx-project.json to declare the namespace prefix at the project level. Configure the source files to use the local-name convention (no prefix in the source) while specifying the namespace in the package metadata. Set up the project's CI pipeline to build packages with the namespace prefix applied. Test by deploying a sample package to a scratch org and confirming the components appear with the correct prefix.
- Audit Apex and dynamic references
Review the Apex codebase for any hardcoded namespace references, dynamic SOQL with component names, and Schema or Type API calls. Update any such references to use the appropriate namespace-aware patterns: UserInfo.getOrganizationNamespace, explicit namespace prefix in cross-package references, prefix-aware string concatenation in dynamic SOQL. Add code review checklist items for namespace awareness so future code stays consistent.
- Test installation in a clean subscriber org
Create a fresh scratch org or sandbox that does not have the namespace prefix. Install the package version through its install URL. Verify that the components appear in the subscriber org with the namespace prefix, that the Apex code runs correctly, and that any cross-package or cross-org references work as expected. Test with a sample customer-added field on a namespaced object to confirm the customer-org-local field works alongside the vendor-shipped fields. Iterate until the install experience is clean.
- The namespace prefix is permanent for the package. Changing it requires creating a new package and migrating subscribers, which is rarely worth the cost.
- Hardcoded namespace strings in Apex break when the code runs outside the namespace. Use namespace-aware utilities for dynamic references.
- Generic component names within a namespace can conflict with standard object names. Choose descriptive prefixes for components even inside the package.
- Cross-package references require the explicit namespace prefix on the referenced component. Local-name references work only within the same package.
- Customer-org-local fields on namespaced objects do not have the prefix. Reports and Apex code that read both vendor-shipped and customer-added fields must handle this correctly.
Trust & references
Straight from the source - Salesforce's reference material on Namespace Prefix.
- Packaging GuideSalesforce Developer Docs
- Salesforce DX Developer GuideSalesforce Developer Docs
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 Namespace Prefix?
Q2. Can you change a namespace prefix after registration?
Q3. What's the character limit?
Discussion
Loading discussion…