Stay organized with collections
Save and categorize content based on your preferences.
Linux
Windows
Use image families to simplify image versioning. Add an image to an image
family to set it as the most recent image version. If you determine that you
must roll back the image family to a previous image version, deprecate
the most recent image in the family.
If you haven't already, set up authentication.
Authentication verifies your identity for access to Google Cloud services and APIs. To run
code or samples from a local development environment, you can authenticate to
Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and
APIs, you don't need to set up authentication.
gcloud
Install the Google Cloud CLI.
After installation,
initialize the Google Cloud CLI by running the following command:
Specify the Name of your image. For example, image-v1.
Specify the Source from which you want to create an image. This can
be a persistent disk, a snapshot, another image, or a disk.raw file in
Cloud Storage.
If you are creating an image from a disk attached to a running VM,
check Keep instance running to confirm that you want to create the
image while the VM is running. You can prepare your VM
before creating the image.
In the Based on source disk location (default) drop-down list,
specify the location to store the image. For example, specify us to
store the image in the us multi-region, or us-central1 to store it in
the us-central1 region. If you do not make a selection,
Compute Engine stores the image in the multi-region closest to
your image's source location.
Specify the image Family for the new image. For example, add
my-image-family to organize the image as part of an
image family.
Specify the encryption key. You can choose between a Google-owned and Google-managed encryption key,
a Cloud Key Management Service (Cloud KMS) key or a customer-
supplied encryption (CSEK)
key. If no encryption key is specified, images are encrypted
using a Google-owned and Google-managed encryption key.
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/family
{
"resourceId":"my-image-family",
}
If you determine that you must roll back the image family so that it no longer
points to image-v2, deprecate image-v2 and the family will again
point to image-v1.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eImage families simplify image versioning by allowing you to group related images and designate the most recent version.\u003c/p\u003e\n"],["\u003cp\u003eAdding a new image to an existing image family automatically sets it as the newest version within that family.\u003c/p\u003e\n"],["\u003cp\u003eYou can manage the storage location of an image during creation using the Google Cloud console, the \u003ccode\u003egcloud compute images create\u003c/code\u003e command, or the \u003ccode\u003eimages().insert\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eRolling back to a previous image version involves deprecating the most recent image, which then reverts the family's pointer to the prior version.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egcloud compute images describe-from-family\u003c/code\u003e command or the \u003ccode\u003eimages().getFromFamily\u003c/code\u003e method allows you to confirm which image a specific image family currently references.\u003c/p\u003e\n"]]],[],null,["Linux Windows\n\n*** ** * ** ***\n\nUse image families to simplify image versioning. Add an image to an image\nfamily to set it as the most recent image version. If you determine that you\nmust roll back the image family to a previous image version, deprecate\nthe most recent image in the family.\n\nFor best practices when working with image families, see\n[Image families best practices](/compute/docs/images/image-families-best-practices).\n\nOptionally, you can specify the\n[image's storage location](#selecting_image_storage_location) by using the\nGoogle Cloud console, the\n[`gcloud compute images create` command](/sdk/gcloud/reference/compute/images/create)\nwith the `--storage-location` flag, or the\n[`images().insert` method](/compute/docs/reference/rest/v1/images/insert).\n\nBefore you begin\n\n- Read the [Images](/compute/docs/images) document.\n- If you haven't already, set up [authentication](/compute/docs/authentication). Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:\n\n Select the tab for how you plan to use the samples on this page: \n\n Console\n\n\n When you use the Google Cloud console to access Google Cloud services and\n APIs, you don't need to set up authentication.\n\n gcloud\n 1.\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n After installation,\n [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command:\n\n ```bash\n gcloud init\n ```\n\n\n If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n | **Note:** If you installed the gcloud CLI previously, make sure you have the latest version by running `gcloud components update`.\n 2. [Set a default region and zone](/compute/docs/gcloud-compute#set_default_zone_and_region_in_your_local_client).\n\n REST\n\n\n To use the REST API samples on this page in a local development environment, you use the\n credentials you provide to the gcloud CLI.\n 1. [Install](/sdk/docs/install) the Google Cloud CLI. After installation, [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command: \n\n ```bash\n gcloud init\n ```\n 2. If you're using an external identity provider (IdP), you must first [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n\n\n For more information, see\n [Authenticate for using REST](/docs/authentication/rest)\n in the Google Cloud authentication documentation.\n\nSet the image version in an image family \n\nConsole\n\n1. In the Google Cloud console, go to the **Create an image** page.\n\n [Go to Create an image](https://console.cloud.google.com/compute/imagesAdd)\n2. Specify the **Name** of your image. For example, `image-v1`.\n\n3. Specify the **Source** from which you want to create an image. This can\n be a persistent disk, a snapshot, another image, or a disk.raw file in\n Cloud Storage.\n\n4. If you are creating an image from a disk attached to a running VM,\n check **Keep instance running** to confirm that you want to create the\n image while the VM is running. You can [prepare your VM](#prepare_instance_for_image)\n before creating the image.\n\n5. In the **Based on source disk location (default)** drop-down list,\n specify the location to store the image. For example, specify `us` to\n store the image in the `us` multi-region, or `us-central1` to store it in\n the `us-central1` region. If you do not make a selection,\n Compute Engine stores the image in the multi-region closest to\n your image's source location.\n\n6. Specify the image **Family** for the new image. For example, add\n `my-image-family` to organize the image as part of an\n [image family](/compute/docs/images#image_families).\n\n7. Optional: specify other image properties:\n\n - **Description**: a description for your custom image.\n - **Label** : a [label](/compute/docs/labeling-resources) to group together resources.\n8. Specify the encryption key. You can choose between a Google-owned and Google-managed encryption key,\n a [Cloud Key Management Service (Cloud KMS)](/kms/docs) key or a [customer-\n supplied encryption (CSEK)](/compute/docs/disks/customer-supplied-encryption)\n key. If no encryption key is specified, images are encrypted\n using a Google-owned and Google-managed encryption key.\n\n9. Click **Create** to create the image.\n\ngcloud \n\n```\ngcloud compute images create image-v1 \\\n --source-disk disk-1 \\\n --source-disk-zone us-central1-f \\\n --family my-image-family\n```\n\nThe image family points to `image-v1`. Add a second image to the family: \n\n```\ngcloud compute images create image-v2 \\\n --source-disk disk-2 \\\n --source-disk-zone us-central1-f \\\n --family my-image-family\n```\n\nREST\n\nMake a `POST` request to the\n[`images().insert` method](/compute/docs/reference/v1/images/insert).\nSpecify the image family in the request body. \n\n```\nPOST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images\n\n{\n \"name\": \"image-v2\",\n \"sourceDisk\": \"/zones/us-central1-f/disks/disk-2\",\n \"family\":\"my-image-family\",\n\n}\n```\n\nThe image family points to `image-v2` because it is the most recent image that\nyou added to the image family. \n\ngcloud\n\nYou can see which image a family points to by running the\n[`gcloud compute images describe-from-family` command](/sdk/gcloud/reference/compute/images/describe-from-family).\n\nFor example: \n\n```\ngcloud compute images describe-from-family my-image-family\n\nfamily: my-image-family\nid: '8904691942610171306'\nkind: compute#image\nname: image-v2\nselfLink: https://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v2\nsourceDisk: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v2\nsourceDiskId: '1677449456001963379'\nsourceType: RAW\nstatus: READY\n```\n\nREST\n\nMake a `GET` request to the\n[`images().getFromFamily` method](/compute/docs/reference/rest/v1/images/getFromFamily).\nSpecify the image family in the request body. \n\n```\nGET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/images/family\n\n{\n \"resourceId\":\"my-image-family\",\n\n}\n```\n\nIf you determine that you must roll back the image family so that it no longer\npoints to `image-v2`, deprecate `image-v2` and the family will again\npoint to `image-v1`. \n\n```\ngcloud compute images deprecate image-v2 \\\n --state DEPRECATED \\\n --replacement image-v1\n```\n\nCheck to make sure that the image family is pointing to `image-v1`. \n\n```\ngcloud compute images describe-from-family my-image-family\n\nfamily: my-image-family\nid: '2741732787056801255'\nkind: compute#image\nname: image-v1\nselfLink: https://compute.googleapis.com/compute/v1/projects/my-project/global/images/image-v1\nsourceDisk: https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-f/disks/disk-v1\nsourceDiskId: '1677449456001963379'\nsourceType: RAW\nstatus: READY\n\n```"]]
