Capture an image

Here we combine API operations to capture a disk from an existing Linode and save it as an image. This stores it for you so you can quickly create new Linodes using the image.

📘

  • When you capture an image, we store it using our Object Storage service. The region where the target image exists determines where the resulting image is stored.
  • When you capture a new image, we automatically encrypt it for its protection. Images remain encrypted at rest, in storage, in caching, and in transit. When you deploy an image, we automatically decrypt the contents for you. Also, if you've enabled encryption for a Linode you want to create an image of, we also encrypt the imagein essence "double encrypting" it. When you deploy that image, we decrypt it and then automatically encrypt the resulting disk.

Before you begin

When capturing an image file from an existing Linode, there are several prerequisites you need to meet.

Get details

First, you need to gather some values for specific resources. Specifically, this includes information on the region where the target Linode lives.

  1. Run the List regions operation.

  2. For the region where your target Linode lives, store its id as your regionId.

    {
      "data": [
        {
          "capabilities": [
            "Linodes",
            "NodeBalancers",
            "Block Storage",
            "Object Storage",
            "Placement Groups",
            "Block Storage Encryption",
            "Linode Interfaces"
          ],
          "country": "us",
          "id": "us-mia", <== Store.
          "label": "Miami, FL, USA",
          ...
        }
      ],
      "page": 1,
      "pages": 1,
      "results": 1
    }
    
  3. Run the List Linodes operation, and include --header X-Filter 'region: <regionId>' in the request. This filters the response based on the target region.

  4. Identify the specific Linode whose disk you want to include in the image. Store its id as your linodeId.

    {
      "data": [
        {
          "alerts": {
            "cpu": 180,
            "io": 10000,
            "network_in": 10,
            "network_out": 10,
            "transfer_quota": 80
          },
          "backups": {
            "available": true,
            "enabled": true,
            "last_successful": "2018-01-01T00:01:01",
            "schedule": {
              "day": "Saturday",
              "window": "W22"
            }
          },
          "capabilities": [
            "Block Storage Encryption"
          ],
          "created": "2018-01-01T00:01:01",
          "disk_encryption": "disabled",
          "has_user_data": true,
          "host_uuid": "1a2bcd34e5f67gh8ij901234567kl89mn01opqr2",
          "hypervisor": "kvm",
          "id": 123, <== Store.
          ...
        }
      ],
      "page": 1,
      "pages": 1,
      "results": 1
    }
    
  5. Run the List disks operation, using the linodeId you stored. In the response, locate the desired disk and store its id as your diskId.

    {
      "data": [
        {
          "created": "2025-01-01T00:01:01",
          "disk_encryption": "disabled",
          "filesystem": "ext4",
          "id": 25674, <== Store.
          "label": "Golden Image 2",
          "size": 48640,
          "status": "ready",
          "updated": "2025-01-01T00:01:01"
        }
      ],
      "page": 1,
      "pages": 1,
      "results": 1
    }
    

Create the image

  1. Run the Create an image operation. Include the following values in the request:Store the id value that's generated for it.

    • disk_id. This is the diskId you stored from the Linode.

    • label. Optionally give your image an easily recognizable name. If this is left out, the name of the image will default to <compute_instance_label>-<disk_name>.

    • tags. For organizational purposes, you can optionally enter one or more tags to group similar objects under these specific values. Once you set one, you can set it again with other images.

    • description. Optionally add some text to describe your image.

    • cloud_init. Set to true if you want the image to support cloud-init. Many Linode-supported distributions are compatible with it by default, or you may have installed cloud-init on the disk, yourself. Our Metadata service is designed to be consumed by cloud-init.

    {
      "disk_id": 25674,
      "label": "Golden Image 2",
      "tags": [
         "gold", "secondary"
      ],
      "description": "Secondary golden image for Debian 11 Linux",
      "cloud_init": "true"
    }
    
  2. From the response, store the id as your imageId.

    {
      "capabilities": [
        "cloud-init",
      ],
      "created": "2025-08-14T22:44:02",
      "created_by": "linode",
      "deprecated": false,
      "description": "Secondary golden image for Debian 11 Linux.",
      "eol": "2026-07-01T04:00:00",
      "expiry": null,
      "id": "private/goldenimage2", <== Store.
      "is_public": true,
      "label": "Golden Image 2",
      "regions": [
        {
          "region": "us-mia",
          "status": "available"
        }
      ],
      "size": 2500,
      "status": "creating",
      ...
    }
    

Check the status

The process takes some time to complete. You can check on it by running the Get an image, using the imageId you stored after creating it.

When the status is available, the image is ready for use.

Deploy your image

When you're ready to add your image as a disk to a Linode, you can follow this workflow.