Namespace
A namespace is a one-to-fifteen-character alphanumeric prefix that identifies a managed package and separates its components from everything else in a customer's org.
Definition
A namespace is a one-to-fifteen-character alphanumeric prefix that identifies a managed package and separates its components from everything else in a customer's org. Once you register it on a Developer Edition org, the prefix attaches to every API name in the package. A custom object MyObject__c becomes acme__MyObject__c, an Apex class is referenced as acme.MyClass, and a Lightning component carries the acme namespace. The prefix stops two different packages from colliding when they both ship a component with the same base name.
The namespace is the backbone of AppExchange packaging. A partner registers one prefix, builds a managed package, and every subscriber who installs it sees that prefix on the installed metadata. Namespaces are case-insensitive and permanent. After you register a prefix you cannot rename it, transfer it, or reuse it, so the choice you make on day one follows the package for its entire life.
How namespaces keep packaged code from colliding
What the prefix actually is
A namespace is a short identifier, between one and fifteen alphanumeric characters, that Salesforce reserves for a single packaging account. It is case-insensitive, so Acme and acme resolve to the same registered value. The prefix has to be unique across the whole AppExchange ecosystem, which is why Salesforce checks availability at registration time and rejects anything already taken. Once the prefix exists, the platform folds it into the API name of every packageable component you create in that org. The pattern for custom objects and fields uses a double underscore: a field named Region__c in an org with the namespace acme is stored and queried as acme__Region__c. Apex classes, triggers, Visualforce pages, and Lightning components follow the same rule with their own separators. This automatic prefixing is the entire point. It guarantees that the components you ship can never clash with the components a customer already built, because the customer's own work has no namespace at all.
Why Salesforce needs them at all
Salesforce is multitenant, and AppExchange lets thousands of partners distribute apps into the same orgs. Without a separation mechanism, two installed packages that each ship an object called Invoice__c would overwrite or shadow each other, and a customer who also built their own Invoice__c would have no way to tell the three apart. Names alone are not enough when the supply of sensible names is small and the number of publishers is large. The namespace solves this by giving each publisher a private corner of the API name space. Package A ships billing__Invoice__c, package B ships finance__Invoice__c, and the customer keeps their plain Invoice__c. All three live in the same org without conflict. The prefix also signals provenance at a glance. When an admin opens the object manager and sees a prefixed API name, they know that component arrived from a package and should usually be changed through the vendor, not edited directly in the subscriber org.
Registering on a Developer Edition org
You register a namespace on a free Developer Edition org, not on your production org and not on your Dev Hub. For first-generation packaging this org is the packaging org, the single place from which you upload package versions. The registration happens in Setup under Package Manager, where you enter a candidate prefix, the platform checks that it is free, and you confirm the choice. Treat that confirmation as final. The prefix cannot be edited after registration, and the Developer Edition org that owns it becomes tied to your package line. For second-generation packaging the model is looser. You still create a namespace-scoped Developer Edition org and link it to your Dev Hub, but the namespace is no longer bound to one packaging org as the sole source of truth. Salesforce recommends keeping this namespace org separate from the Dev Hub org so the two responsibilities, hosting packages and reserving the name, stay cleanly divided.
Referencing packaged code from outside
Inside a managed package, code refers to its own components by their plain names. An Apex class in the acme package calls MyClass.method() without writing the prefix, because the platform already knows the package context. The namespace is implied for any reference that stays inside the package boundary. Code that lives outside the package has to be explicit. A subscriber-org Apex script that calls a global method in an installed package writes acme.MyClass.method(). A Lightning Web Component imports a packaged Apex method as @salesforce/apex/acme.MyClass.myMethod, and a SOQL query against a packaged object names acme__MyObject__c in full. The same applies to dynamic references such as Type.forName, where you pass the namespace as a separate argument. Forgetting the prefix in cross-package code is one of the most common reasons a working call in the packaging org fails after install, because the names that resolved implicitly inside the package no longer resolve from the outside.
First-generation versus second-generation behavior
First-generation managed packages (1GP) bind the namespace to one packaging org. That org holds the metadata, owns the prefix, and is the only place a new version can be uploaded. The workflow grew up before source control was the norm, so the packaging org effectively is the package. Second-generation managed packages (2GP) decouple the namespace from any single org. The prefix is assigned to a package at creation time and still cannot be changed, but one namespace can be shared across several 2GP packages. Salesforce actually recommends using a single namespace for all of your managed 2GP packages, because shared code is far easier to reuse when the packages share a prefix. This model fits modern, source-driven development where the project lives in a repository and scratch orgs are spun up on demand. For any new partner work, 2GP is the direction Salesforce points teams toward, while 1GP remains in place for long-lived existing packages.
Namespaces in customer and unlocked-package orgs
Most customer orgs never register a namespace. Custom objects, fields, and classes built by an admin or in-house developer carry no prefix, which is why a plain Account custom field looks like Discount__c rather than something__Discount__c. The absence of a prefix is itself a useful signal that a component is local rather than installed. Two situations push a customer toward registering one anyway. Some organizations adopt unlocked packages to modularize their own internal metadata across many orgs, and a namespace can help keep those modules tidy and portable. Others build their own 2GP managed packages for internal distribution. In both cases the same permanence rule applies, so a customer who registers a namespace is making a long-term commitment. Because the prefix can never be removed from existing components, teams usually weigh this carefully before adding one to metadata that started life unprefixed.
How to register a namespace for a managed package
Registering a namespace is a one-time action you take on a dedicated Developer Edition org before you build a managed package. Pick the prefix with care, because it is permanent once confirmed.
- Create a clean Developer Edition org
Sign up for a fresh Developer Edition org reserved for packaging. Do not reuse a sandbox, a production org, or your Dev Hub org for this. The org you choose becomes the long-term home of the namespace.
- Open the namespace registration screen
In Setup, enter Package Manager in Quick Find and open it. If no namespace is registered yet, the page shows an option to register one. Start there.
- Enter and check a candidate prefix
Type a one-to-fifteen-character alphanumeric prefix that reflects your company or product. The platform checks availability across AppExchange in real time and rejects any value already taken.
- Review and confirm
Confirm the prefix only when you are certain. After you save, the namespace is locked to this org and applied to every packaged component, with no option to rename or transfer it later.
One to fifteen alphanumeric characters, case-insensitive, that begins with a letter and is unique across AppExchange. This becomes the prefix on every component in the package.
The dedicated org that owns the namespace. For 1GP this is your packaging org; for 2GP it is a namespace org linked to your Dev Hub.
- The prefix is permanent. You cannot rename, transfer, or reuse a registered namespace, so test candidate names against your branding before you confirm.
- You cannot register a namespace on an org that already contains a managed package, which is one more reason to use a fresh Developer Edition org.
- Cross-package references break if you omit the prefix. Code that worked unprefixed inside the packaging org must use namespace.Class or namespace__Object__c once called from a subscriber org.
Prefer this walkthrough as its own page? How to Namespace in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Namespace.
Hands-on resources to go deeper on Namespace.
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 Namespace prefix do to the API names of components shipped in a managed package?
Q2. What core Salesforce reality makes Namespaces necessary in the first place?
Q3. Once a Namespace prefix is assigned to a Developer Edition org, what is true about it?
Discussion
Loading discussion…