Instance Image
When creating a TIR instance, you choose the base environment your instance runs on. TIR supports three image types: Pre-built, Base OS, and Custom. Choosing the right image type determines how much setup is required and how much control you have over the environment.
| Image Type | Description | Best For |
|---|---|---|
| Pre-built | Ready-to-use ML environments with CUDA and dependencies pre-configured | Getting started quickly with standard frameworks |
| Base OS | Minimal Ubuntu image with no pre-installed packages | Full environment control with custom dependencies |
| Custom | Public or private container images from external or internal registries | Team-shared environments, saved states, or community images |
Image Types
Pre-built
Pre-built images are maintained by TIR and include popular machine learning frameworks with all required drivers and dependencies configured out of the box.
These environments come with pre-configured and tested CUDA versions and library dependencies, allowing you to start working immediately without manual setup.
Use Pre-built when:
- You want to start working immediately without managing dependencies or environment setup.
Note: JupyterLab is supported for pre-built images.
Available machine images include: Transformers, PyTorch, TensorFlow 2, Diffusers, NVIDIA NeMo, NVIDIA RAPIDS, FastAI, vLLM, ComfyUI, FramePack, Triton Inference Server, Ubuntu 24.04, TensorRT LLM Engine Builder, NVIDIA Riva Speech, PaddleOCR, and more.
View the full list on the Supported Image List page.
Base OS
Base OS images provide a minimal Ubuntu environment. No ML frameworks or additional packages are pre-installed.
Use Base OS when:
- You need full control over installed packages.
- Your workload requires specific library versions that may conflict with pre-built environments.
Note: JupyterLab is not supported for Base OS images.
Custom
Custom images let you bring your own container image from a public or private registry.
There are two sub-types:
- Public — Images hosted on Docker Hub or other public registries, maintained by the community or vendors.
- Private — Your own images stored in the TIR Container Registry or built using the TIR Image Builder.
When to Use a Private Image
| Scenario | Description |
|---|---|
| Saved environment | You previously saved an instance state using Save Image and want to restore it on a new instance. |
| Custom framework | Your project uses a container image with specific libraries, drivers, or configurations not available in the public catalog. |
| Shared project image | Multiple project members need to launch from the same standardized environment stored in a shared registry. |
When to Use a Public Image
| Scenario | Description |
|---|---|
| Docker Hub image | You want to launch from a public image available on Docker Hub or another public registry. |
| Community-maintained image | The image you need is not in the TIR public catalog but is available from a community or vendor source. |
Launching an Instance with a Custom Image
This section walks through the steps to create an instance using either a private or public custom image.
Note: Using Private is the recommended approach when restoring a saved environment via Save Image, or when your team maintains a shared container image in a registry.
Step 1: Open the Create Instance Flow
Navigate to Instances from the left sidebar and click Create Instance.
Step 2: Configure the Image
In the image configuration section, set the image type to Custom, then select either Private or Public.
For Private Image
- Select the registry namespace from the dropdown. This lists namespaces configured in your TIR Container Registry.
- Select the image from the available images within that namespace.
- On the next page, select the desired image version from the dropdown in the top-right corner.
JupyterLab Support: Enable the JupyterLab Support checkbox if your image supports JupyterLab. This is required to activate the JupyterLab interface for the instance. Check this if your image was built using the TIR Image Builder or is based on a TIR pre-built image.
For Public Image
- Enter the full public Docker image URL or image name (e.g.,
pytorch/pytorch:latestfrom Docker Hub). - Click Next to proceed.
Step 3: Complete Instance Configuration
Configure the remaining instance settings such as compute plan and workspace storage, then click Launch.
The instance will start using your selected image.
Best Practices for Using Private Images
Avoid relying on the latest tag for production workloads. Use explicit version tags (for example, v1.2) so you can reliably reproduce the same environment.
Check the JupyterLab Support option only if your image was built using TIR's image builder utility or is based on a TIR prebuilt image that supports JupyterLab.
Ensure the Container Registry namespace is configured in your project under Platform Services before launching. The namespace must exist for the image selection to populate.
Periodically rebuild and push updated images to your registry to keep dependencies and security patches current in your private images.