Managing Namespaces
This page covers namespace operations for open source Temporal. For core namespace concepts, see Temporal Namespace. For Temporal Cloud, see Temporal Cloud Namespaces.
A Namespace is a unit of isolation within the Temporal Platform. Before you can run Workflows, you must register at least one Namespace with your Temporal Service.
Create a Namespace
Registering a Namespace creates it on the Temporal Service. When you register a Namespace, you must set a Retention Period that determines how long closed Workflow execution history is kept.
You can create Namespaces using:
- Temporal CLI (recommended):
temporal operator namespace create - Go SDK:
RegisterNamespace - Java SDK:
RegisterNamespace - TypeScript SDK: Namespace management
The default Namespace
If no Namespace is specified, SDKs and CLI use the default Namespace.
You must register this Namespace before using it.
When deploying with Docker Compose or the auto-setup image, the default Namespace is created automatically.
When deploying with Helm charts, create it manually:
temporal operator namespace create --namespace default
Namespace registration takes up to 15 seconds to complete. Wait for this process to finish before making calls to the Namespace.
Manage Namespaces
Common namespace management operations:
| Operation | CLI Command | Description |
|---|---|---|
| List | temporal operator namespace list | List all registered Namespaces |
| Describe | temporal operator namespace describe | Get details for a Namespace |
| Update | temporal operator namespace update | Update Namespace configuration |
| Delete | temporal operator namespace delete | Delete a Namespace and all its data |
For SDK-based namespace management:
Deprecate vs Delete
- Deprecate: Prevents new Workflow Executions from starting, but existing Workflows continue to run.
- Delete: Removes the Namespace and all Workflow Executions. This is irreversible.
Security
Use a custom Authorizer on your Frontend Service to control who can create, update, or deprecate Namespaces.
Without an Authorizer configured, Temporal uses the nopAuthority authorizer that allows all API calls unconditionally.
For Temporal Cloud, role-based access controls provide namespace-level authorization without custom configuration.
Best practices
For namespace naming conventions, organizational patterns, and production safeguards, see Namespace Best Practices.