Create an image definition and an image version


This article references CentOS, a Linux distribution that is End Of Life (EOL) status. Please consider your use and plan accordingly. For more information, see the CentOS End Of Life guidance.

An Azure Compute Gallery (formerly known as Shared Image Gallery) simplifies custom image sharing across your organization. Custom images are like marketplace images, but you create them yourself. Images can be created from a VM, VHD, snapshot, managed image, or another image version.

The Azure Compute Gallery lets you share your custom VM images with others in your organization, within or across regions, within a Microsoft Entra tenant, or publicly using a community gallery. Choose which images you want to share, which regions you want to make them available in, and who you want to share them with. You can create multiple galleries so that you can logically group images. Many new features like ARM64, Accelerated Networking and TrustedVM are only supported through Azure Compute Gallery and not available for managed images.

The Azure Compute Gallery feature has multiple resource types:

Resource Description
Image source This is a resource that can be used to create an image version in a gallery. An image source can be an existing Azure VM that is either generalized or specialized, a managed image, a snapshot, or an image version in another gallery.
Gallery Like the Azure Marketplace, a gallery is a repository for managing and sharing images and VM applications, but you control who has access.
Image definition Image definitions are created within a gallery and carry information about the image and requirements for using it internally. This includes whether the image is Windows or Linux, release notes, and minimum and maximum memory requirements. It is a definition of a type of image.
Image version An image version is what you use to create a VM when using a gallery. You can have multiple versions of an image as needed for your environment. Like a managed image, when you use an image version to create a VM, the image version is used to create new disks for the VM. Image versions can be used multiple times.

Before you begin

To complete this article, you must have an existing Azure Compute Gallery, and a source for your image available in Azure. Image sources can be:

  • A VM in your subscription. You can capture an image from both specialized and generalized VMs.
  • A Managed image,
  • Managed OS and data disks.
  • OS and data disks as VHDs in a storage account.
  • Other image versions either in the same gallery or another gallery in the same subscription.

If the image will contain data disks, the data disk size cannot be more than 1 TB.

Image definition names can be made up of uppercase or lowercase letters, digits, dots, dashes and periods. For more information about the values you can specify for an image definition, see Image definitions.

Allowed characters for the image version are numbers and periods. Numbers must be within the range of a 32-bit integer. Format: MajorVersion.MinorVersion.Patch.

When working through this article, replace the resource names where needed.

For generalized images, see the OS specific guidance before capturing the image:

If you will be sharing your images using a community gallery, make sure that you create your gallery, image definitions, and image versions in the same region.

When users search for community gallery images, only the latest version of an image is shown.


Information from your image definitions will be publicly available, like what you provide for Publish, Offer, and SKU.

Create an image

Choose an option below for creating your image definition and image version:

To create an image from a VM in the portal, see Capture an image of a VM.

To create an image using a source other than a VM, follow these steps.

  1. Go to the Azure portal, then search for and select Azure Compute Gallery.

  2. Select the gallery you want to use from the list.

  3. On the page for your gallery, select Add from the top of the page and then select VM image definition from the drop-down.

  4. on the Add new image definition to Azure Compute Gallery page, in the Basics tab, select a Region.

  5. For Image definition name, type a name like myImageDefinition.

  6. For Operating system, select the correct option based on your source.

  7. For VM generation, select the option based on your source. In most cases, this will be Gen 1. For more information, see Support for generation 2 VMs.

  8. For Operating system state, select the option based on your source. For more information, see Generalized and specialized.

  9. For Publisher, type a unique name like myPublisher.

  10. For Offer, type a unique name like myOffer.

  11. For SKU, type a unique name like mySKU.

  12. At the bottom of the page, select Review + create.

  13. After the image definition passes validation, select Create.

  14. When the deployment is finished, select Go to resource.

  15. In the page for your image definition, on the Get started tab, select Create a version.

  16. In Region, select the region where you want the image created. In some cases, the source must be in the same region where the image is created. If you aren't seeing your source listed in later drop-downs, try changing the region for the image. You can always replicate the image to other regions later.

  17. For Version number, type a number like 1.0.0. The image version name should follow major.minor.patch format using integers.

  18. In Source, select the type of file you are using for your source from the drop-down. See the table below for specific details for each source type.

    Source Other fields
    Disks or snapshots - For OS disk select the disk or snapshot from the drop-down.
    - To add a data disk, type the LUN number and then select the data disk from the drop-down.
    Image version - Select the Source gallery from the drop-down.
    - Select the correct image definition from the drop-down.
    - Select the existing image version that you want to use from the drop-down.
    Managed image Select the Source image from the drop-down.
    The managed image must be in the same region that you chose in Instance details.
    VHD in a storage account Select Browse to choose the storage account for the VHD.
  19. In Exclude from latest, leave the default value of No unless you don't want this version used when creating a VM using latest instead of a version number.

  20. For End of life date, select a date from the calendar for when you think this version should stop being used.

  21. In the Replication tab, select the storage type from the drop-down.

  22. Set the Default replica count, you can override this for each region you add.

  23. You need to replicate to the source region, so the first replica in the list will be in the region where you created the image. You can add more replicas by selecting the region from the drop-down and adjusting the replica count as necessary.

  24. When you are done, select Review + create. Azure will validate the configuration.

  25. When image version passes validation, select Create.

  26. When the deployment is finished, select Go to resource.

It can take a while to replicate the image to all of the target regions.

You can also capture an existing VM as an image, from the portal. For more information, see Create an image of a VM in the portal.

Create an image in one tenant using the source image in another tenant

In the subscription where the source image exists, grant reader permissions to the user. Once the user has reader permission to the source image, login to both accounts (source and target).

You will need the tenantID of the source image, the subscriptionID for the subscription where the new image will be stored (target), and the resourceID of the source image. Additionally, you need to ensure that the source image's region or replica and target region are the same.

# Set some variables
tenantID="<tenant ID for the source image>"
subID="<subscription ID where the image will be creted>"
sourceImageID="<resource ID of the source image>"

# Login to the subscription where the new image will be created
az login

# Log in to the tenant where the source image is available
az login --tenant $tenantID

# Log back in to the subscription where the image will be created and ensure subscription context is set
az login
az account set --subscription $subID

# Create the image
az sig image-version create `
   --gallery-image-definition myImageDef `
   --gallery-image-version 1.0.0 `
   --gallery-name myGallery `
   --resource-group myResourceGroup `
   --image-version $sourceImageID
   --location myLocation

Next steps

For information about how to supply purchase plan information, see Supply Azure Marketplace purchase plan information when creating images.