---
title: Custom ISO
url: https://docs.vultr.com/products/compute/instances/optimized-cloud-compute/management/custom-iso
description: A feature that allows you to upload and attach your own ISO image to Vultr instances for custom operating system installations.
publish_date: 2025-01-15T16:46:34.200164Z
last_updated: 2026-05-26T18:45:11.296465Z
---

# How to Attach a Custom ISO to a Vultr Optimized Cloud Compute Instance

ISO images allow you to install a specific operating system on an Vultr Optimized Cloud Compute instance. Custom ISOs enable you to deploy operating systems not available in the default Vultr installer list. They are useful for creating tailored environments or booting into specialized modes, such as rescue and recovery environments.

Follow this guide to attach a custom ISO to a Vultr Optimized Cloud Compute instance using the Vultr Console, API, CLI, or Terraform.

> [!WARNING]
> Installing a custom ISO on a Vultr Optimized Cloud Compute instance disables the default user credentials listed in your instance's management page.

=== "Vultr Console"

    1. Navigate to **Products** and click **Compute**.
    1. Click your target Vultr Optimized Cloud Compute instance to open its management page.
    1. Navigate to the **Settings** tab.
    1. Find and click **Custom ISO** on the left navigation menu.
    1. Select a custom ISO available in your Vultr account or click the **ISO Library** drop-down to select from a list of public ISOs.
    1. Click **Attach ISO and Reboot** to attach the ISO to your instance.

=== "Vultr API"

    1. Send a `GET` request to the [**List Instances** endpoint](https://www.vultr.com/api/#tag/instances/operation/list-instances) and note your target instance's ID.

        ```console
        $ curl "https://api.vultr.com/v2/instances" \
          -X GET \
          -H "Authorization: Bearer ${VULTR_API_KEY}"
        ```

    1. Send a `GET` request to the [**List ISOs** endpoint](https://www.vultr.com/api/#tag/iso/operation/list-isos) and note your target ISO ID.

        ```console
        $ curl "https://api.vultr.com/v2/iso" \
          -X GET \
          -H "Authorization: Bearer ${VULTR_API_KEY}"
        ```

    1. Send a `POST` request to the [**Attach ISO to Instance** endpoint](https://www.vultr.com/api/#tag/instances/operation/attach-instance-iso) to attach the ISO to your target instance.

        ```console
        $ curl "https://api.vultr.com/v2/instances/{instance-id}/iso/attach" \
          -X POST \
          -H "Authorization: Bearer ${VULTR_API_KEY}" \
          -H "Content-Type: application/json" \
          --data '{
            "iso_id" : "<iso-id>"
          }'
        ```

=== "Vultr CLI"

    1. List all available instances and note your target instance's ID.

        ```console
        $ vultr-cli instance list
        ```

    1. List all available ISO images and note your target ISO's ID.

        ```console
        $ vultr-cli iso list
        ```
    
    1. Attach the ISO to your target instance.

        ```
        $ vultr-cli instance iso attach <instance-id> \
                    --iso-id="<iso-id>"
        ```

=== "Terraform"

    1. Open your Terraform configuration for the existing Optimized Cloud Compute instance.

    1. Specify the ISO by its `os_id` when defining or rebuilding the instance.

        ```terraform
        # Example: attach a custom ISO by its ID (replace 159 with your ISO ID)
        resource "vultr_instance" "occ" {
            label    = "occ-custom-iso"
            region   = "del"
            plan     = "vhp-2c-4gb"
            os_id    = 159                 # 'Custom' ISO type
            iso_id   = "your-iso-id-here"  # ID of uploaded or library ISO
            hostname = "occ-custom-iso"
        }
        ```

    1. Apply the configuration and observe the following output:

        ```
        Apply complete! Resources: 0 added, 1 changed, 0 destroyed.
        ```

    > [!NOTE]
    > Terraform does not currently support **attaching an ISO in-place** to a running instance.  
    > The ISO must be set at **create time** or during a **rebuild**, which replaces the instance and wipes all existing data.