# Template tags & versioning (/docs/template/tags)

<!-- agent-signals: reading_time_min: 6 · est_tokens: 3362 · 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 versioning allows you to maintain multiple versions of the same template using tags. This enables workflows like semantic versioning, environment-based deployments, and gradual rollouts.

## Tag format [#tag-format]

Tags follow the `name:tag` format, where `name` is your template's identifier and `tag` is the version label.

```
my-template:v1.0.0              // Within your project
my-template:production          // Within your project
acme/my-template:v1.0.0         // Full namespaced reference
```

## The default tag [#the-default-tag]

When you build or reference a template without specifying a tag, E2B uses the `default` tag automatically. This means:

* `my-template` is equivalent to `my-template:default`
* Existing templates without tags continue to work seamlessly

<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  
      // These are equivalent
      const sandbox1 = await Sandbox.create('my-template')
      const sandbox2 = await Sandbox.create('my-template:default')
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # These are equivalent
      sandbox1 = Sandbox.create('my-template')
      sandbox2 = Sandbox.create('my-template:default')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Referencing a specific build [#referencing-a-specific-build]

Instead of using a named tag, you can start a sandbox from a specific build by passing its `build_id` directly. This is useful when you need to pin a sandbox to an exact build artifact — for example, during debugging or when reproducing an issue from a known build.

The format follows the same colon syntax as tags: `<template>:<build_id>` or `<namespace>/<template>:<build_id>`.

You can find the `build_id` from the return value of `Template.build()` or by listing tags with `Template.getTags()` / `Template.get_tags()`.

<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 { Sandbox } from 'e2b'

      // Start a sandbox from a specific build ID
      const sandbox = await Sandbox.create('my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')

      // With namespace
      const sandbox2 = await Sandbox.create('acme/my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')
      ```
    </CodeBlockTab>

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

      # Start a sandbox from a specific build ID
      sandbox = Sandbox.create('my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')

      # With namespace
      sandbox2 = Sandbox.create('acme/my-template:f47ac10b-58cc-4372-a567-0e02b2c3d479')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Building with tags [#building-with-tags]

You can build templates with one or more tags to create versioned builds.

### Single tag [#single-tag]

<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'

      // Build with a specific version tag
      await Template.build(template, 'my-template:v1.0.0')
      ```
    </CodeBlockTab>

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

      # Build with a specific version tag
      Template.build(template, 'my-template:v1.0.0')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Multiple tags [#multiple-tags]

Build with multiple tags to assign several version labels to the same build artifact.

<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'

      // Build with multiple tags pointing to the same artifact
      await Template.build(template, 'my-template', { tags: ['v1.2.0', 'latest'] })
      ```
    </CodeBlockTab>

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

      # Build with multiple tags pointing to the same artifact
      Template.build(template, 'my-template', tags=['v1.2.0', 'latest'])
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Managing tags [#managing-tags]

You can manage tags on existing template builds without rebuilding.

### Assign tags [#assign-tags]

Assign new tag(s) to an existing build. This is useful for promoting a tested version to production or marking a version as stable.

<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'

      // Assign a single tag
      await Template.assignTags('my-template:v1.2.0', 'production')

      // Assign multiple tags at once
      await Template.assignTags('my-template:v1.2.0', ['production', 'stable'])
      ```
    </CodeBlockTab>

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

      # Assign a single tag
      Template.assign_tags('my-template:v1.2.0', 'production')

      # Assign multiple tags at once
      Template.assign_tags('my-template:v1.2.0', tags=['production', 'stable'])
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Remove tags [#remove-tags]

Remove a tag from a template. The underlying build artifact remains accessible via other tags.

<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'

      // Remove a tag
      await Template.removeTags('my-template', 'staging')
      ```
    </CodeBlockTab>

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

      # Remove a tag
      Template.remove_tags('my-template', 'staging')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Warning>
  Removing a tag does not delete the build artifact. Other tags pointing to the same build will continue to work.
</Warning>

### List tags [#list-tags]

Retrieve all tags for a template. Each tag includes the tag name, the associated build ID, and when the tag was assigned.

<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 tags = await Template.getTags('my-template')
      for (const tag of tags) {
        console.log(`Tag: ${tag.tag}, Build: ${tag.buildId}, Created: ${tag.createdAt}`)
      }
      ```
    </CodeBlockTab>

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

      tags = Template.get_tags('my-template')
      for tag in tags:
          print(f"Tag: {tag.tag}, Build: {tag.build_id}, Created: {tag.created_at}")
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Use cases [#use-cases]

### Semantic versioning [#semantic-versioning]

Use semantic version tags to track releases and enable rollbacks.

<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  
      // Release versions
      await Template.build(template, 'api-server:v1.0.0')
      await Template.build(template, 'api-server:v1.1.0')
      await Template.build(template, 'api-server:v2.0.0')

      // Create sandbox from specific version
      const sandbox = await Sandbox.create('api-server:v1.1.0')
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # Release versions
      Template.build(template, 'api-server:v1.0.0')
      Template.build(template, 'api-server:v1.1.0')
      Template.build(template, 'api-server:v2.0.0')

      # Create sandbox from specific version
      sandbox = Sandbox.create('api-server:v1.1.0')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Environment tags [#environment-tags]

Use environment tags for deployment pipelines.

<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 new version
      await Template.build(template, 'my-app:v1.5.0')

      // Promote through environments
      await Template.assignTags('my-app:v1.5.0', 'staging')

      // After testing, promote to production
      await Template.assignTags('my-app:v1.5.0', 'production')

      // Use in your application
      const env = process.env.NODE_ENV
      const sandbox = await Sandbox.create(`my-app:${env}`)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      import os

      # Build new version
      Template.build(template, 'my-app:v1.5.0')

      # Promote through environments
      Template.assign_tags('my-app:v1.5.0', 'staging')

      # After testing, promote to production
      Template.assign_tags('my-app:v1.5.0', 'production')

      # Use in your application
      env = os.environ.get('ENV', 'staging')
      sandbox = Sandbox.create(f'my-app:{env}')
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Latest and stable tags [#latest-and-stable-tags]

Maintain rolling tags that always point to specific versions.

<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 with version and latest tag
      await Template.build(template, 'my-tool', { tags: ['v3.0.0', 'latest'] })

      // Mark a tested version as stable
      await Template.assignTags('my-tool:v2.9.0', 'stable')

      // You can choose your risk tolerance
      const latestSandbox = await Sandbox.create('my-tool:latest')  // Newest
      const stableSandbox = await Sandbox.create('my-tool:stable')  // Tested
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python  
      # Build with version and latest tag
      Template.build(template, 'my-tool', tags=['v3.0.0', 'latest'])

      # Mark a tested version as stable
      Template.assign_tags('my-tool:v2.9.0', 'stable')

      # You can choose your risk tolerance
      latest_sandbox = Sandbox.create('my-tool:latest')  # Newest
      stable_sandbox = Sandbox.create('my-tool:stable')  # Tested
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>