# Template name
<subtitle>Understanding and managing template names</subtitle>

The template name is a unique identifier used to reference and create sandboxes from the template. They serve as human-readable names that allow you to easily identify and use the template in your application.

## What is a template name?

The name is a string identifier that you assign to the template when you build it. Once you have built a template with a name, you can create a sandbox from the template using that name.

```python
# Build template using name
Template.build(
    template,
    'my-python-env',
    cpu_count=2,
    memory_mb=2048,
)

#Create a sandbox with name
sandbox = Sandbox.create('my-python-env')
```

## Name format

Spaces around the name are trimmed and converted to lowercase before being used. The result must match the pattern `^[a-z0-9-_]+$`:

- Lowercase letters (`a`–`z`), numbers (`0`–`9`), dashes (`-`), and underscores (`_`)
- Length between 1 and 128 characters
- Allows leading and trailing dashes or underscores

Uppercase letters are accepted and automatically converted to lowercase when typing, so `My-Template` and `my-template` refer to the same name. Any other characters (spaces, dots, slashes, etc. within the name) will be rejected.

## Project scope naming

Template names are limited to your project. This means:

- Your template named `my-app` is stored as `<project-id>/my-app`, for example `6173323/my-app`
- You can simply reference it as `my-app` within the same project
- Different projects can have their own `my-app` templates without conflict
- The full namespace format (`<project-id>/template-name`) is required when referencing templates across projects

> The project ID can be viewed in the project settings in the UCloud console.

## Common use cases

### Development and production environments

Use different names for different environments:

```python
#Develop 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,
)
```

### Multiple template variations

Create different variations of the same template with different configurations:

```python
# Small instance
Template.build(
    template,
    'myapp-small',
    cpu_count=1,
    memory_mb=512,
)

# Large instances
Template.build(
    template,
    'myapp-large',
    cpu_count=8,
    memory_mb=8192,
)
```

> When building variants using the same template definition but different CPU/RAM configurations, UCloud Sandbox's caching system will reuse the common layer, making subsequent builds faster.

## Check name availability

You can use the `exists` method to check if a name is already in use within a team.

```python
from ucloud_sandbox import Template

exists = Template.exists('my-template')
print(f"name {'already occupied' if exists else 'available'}")
```

## Best Practices

1. **Use descriptive names**: Choose a name that clearly indicates the purpose or configuration of the template
2. **Use tags for version control**: Do not include the version number in the name, but use [tag](/docs/agent-sandbox/template/tags.md) for version control (for example, `myapp:v1`, `myapp:v2`)
3. **Use consistent naming**: Establish a naming convention for your team and stick to it