# Template names (/docs/template/names)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1752 · updated: 2026-07-30 -->
Related: [Quickstart](/docs/template/quickstart.md), [How it works](/docs/template/how-it-works.md), [User and workdir](/docs/template/user-and-workdir.md), [Caching](/docs/template/caching.md), [Base image](/docs/template/base-image.md), [Private registries](/docs/template/private-registries.md)

Template names are unique identifiers used to reference and create sandboxes from your templates. They serve as human-readable names that make it easy to identify and use your templates across your applications.

## What is a template name? [#what-is-a-template-name]

A name is a string identifier that you assign to a template when building it. Once a template is built with a name, you can use that name to create sandboxes from the template.

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript  
      // Build a template with a name
      await Template.build(template, 'my-python-env', {
        cpuCount: 2,
        memoryMB: 2048,
      })

      // Create a sandbox using the name
      const sandbox = await Sandbox.create('my-python-env')
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # Build a template with a name
      Template.build(
          template,
          'my-python-env',
          cpu_count=2,
          memory_mb=2048,
      )

      # Create a sandbox using the name
      sandbox = Sandbox.create('my-python-env')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Name format [#name-format]

Before a name is used, it's trimmed of surrounding whitespace and lowercased. The result must match the pattern `^[a-z0-9-_]+$`:

* Lowercase letters (`a`–`z`), numbers (`0`–`9`), dashes (`-`), and underscores (`_`)
* Between 1 and 128 characters
* Leading and trailing dashes or underscores are allowed

Uppercase letters are accepted on input and lowercased automatically, so `My-Template` and `my-template` refer to the same name. Any other character (spaces inside the name, dots, slashes, and so on) is rejected.

## Project-local naming [#project-local-naming]

Template names are scoped to your project. This means:

* Your template named `my-app` is stored as `your-project-slug/my-app`
* You can reference it simply as `my-app` within your project
* Other projects can have their own `my-app` template without conflict
* Public templates should be referenced using the full namespaced format (`project-slug/template-name`)

<Info>
  **Backwards Compatibility**: Existing public templates remain accessible without the project slug prefix. New public templates should be referenced using the full namespaced format (`project-slug/template-name`).
</Info>

## Common use cases [#common-use-cases]

### Development and production environments [#development-and-production-environments]

Use different names for different environments:

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript  
      // Development template
      await Template.build(template, 'myapp-dev', {
        cpuCount: 1,
        memoryMB: 1024,
      })

      // Production template
      await Template.build(template, 'myapp-prod', {
        cpuCount: 4,
        memoryMB: 4096,
      })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # Development template
      Template.build(
          template,
          'myapp-dev',
          cpu_count=1,
          memory_mb=1024,
      )

      # Production template
      Template.build(
          template,
          'myapp-prod',
          cpu_count=4,
          memory_mb=4096,
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Multiple template variants [#multiple-template-variants]

Create different variants of the same template with different configurations:

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript  
      // Small instance
      await Template.build(template, 'myapp-small', {
        cpuCount: 1,
        memoryMB: 512,
      })

      // Large instance
      await Template.build(template, 'myapp-large', {
        cpuCount: 8,
        memoryMB: 8192,
      })
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # Small instance
      Template.build(
          template,
          'myapp-small',
          cpu_count=1,
          memory_mb=512,
      )

      # Large instance
      Template.build(
          template,
          'myapp-large',
          cpu_count=8,
          memory_mb=8192,
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Tip>
  When building variants with the same template definition but different CPU/RAM configurations, E2B's caching system will reuse common layers, making subsequent builds much faster.
</Tip>

## Checking name availability [#checking-name-availability]

You can check if a name is already in use within your project with the `exists` method.

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```typescript  
      import { Template } from 'e2b'

      const exists = await Template.exists('my-template')
      console.log(`Name ${exists ? 'is taken' : 'is available'}`)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      from e2b import Template

      exists = Template.exists('my-template')
      print(f"Name {'is taken' if exists else 'is available'}")
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Best practices [#best-practices]

1. **Use descriptive names**: Choose names that clearly indicate the template's purpose or configuration
2. **Use tags for versioning**: Instead of baking version numbers into names, use [tags](/docs/template/tags) for version management (e.g., `myapp:v1`, `myapp:v2`)
3. **Use consistent naming**: Establish a naming convention for your project and stick to it