---
title: Instance Image
---

import { InstanceImageBestPracticesCard } from './InstanceImageCards'

# 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.
<br />
**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](/api/tir/#/paths/gpu_service-image/get) 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

1. Select the **registry namespace** from the dropdown. This lists namespaces configured in your TIR Container Registry.
2. Select the **image** from the available images within that namespace.
3. 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

1. Enter the full public Docker image URL or image name (e.g., `pytorch/pytorch:latest` from Docker Hub).
2. 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.

---
<InstanceImageBestPracticesCard />


---