All Products
Search

This Product

    Platform For AI:Custom images

    Document Center

    Platform For AI:Custom images

    Last Updated:Mar 01, 2026

    With PAI custom images, you can import existing container images or build new ones directly on the platform. Custom images support diverse training workflows while improving productivity.

    Prerequisites

    Before you begin, ensure the following:

    • Alibaba Cloud account: PAI activated and a workspace created.

    • ACR setup: For Enterprise Edition images, create an ACR Enterprise Edition instance with a namespace and repository.

    • Permissions:

      • Alibaba Cloud account: Has all permissions by default.

      • RAM user: Must be added as a workspace member with assigned role permissions. For more information, see Manage workspace members and roles.

    Overview

    PAI provides two methods for adding custom images:

    Method

    Best for

    Complexity

    Import existing image

    Reusing images you've already built

    Medium - requires manual ACR setup

    Build new image

    Creating images from scratch using PAI

    Low - one-stop workflow

    • Import existing image: Build an image locally or on ECS, push it to ACR, and register it in PAI. Best for reusing existing images.

    • Build new image: Configure ACR destination, runtime, and build settings in the PAI console. PAI builds, pushes, and registers the image automatically. Streamlined workflow for building and registering images in one place.

    Method 1: Import an existing image

    Use this method to register an image you've already pushed to ACR.

    Procedure

    1. Open the PAI console and select your workspace.

    2. Navigate to AI Asset Management > Images.

    3. On the Custom Image tab, click Register Image, and select Import Existing Image.

    4. Configure the following parameters:

    Register Image dialog - Import Existing Image

    Parameter

    Description

    Image Type

    Enterprise Edition Instance / Image Namespace / Image Repository / Image Version / Custom Domain Name

    Select an existing instance, namespace, repository, version, and custom domain name, or go to the Container Registry console to create them.

    Note

    • The Enterprise Edition Instance and Custom Domain Name parameters are required only for Enterprise Edition images.

    • If you encounter a permission error, grant AliyunContainerRegistryReadOnlyAccess to your RAM user. For more information, see Manage RAM user permissions.

    Visibility

    • Visible to Me: Only you and workspace administrators can see this image.

    • Visible to Current Workspace: All workspace members can see this image.

    Chip Type

    Select CPU or GPU to match your target hardware.

    1. Click Confirm to register the image.

    Method 2: Build a new image

    Use this method to build a custom image directly in PAI. Currently, only Enterprise Edition images can be built.

    Procedure

    1. Open the PAI console and select your workspace.

    2. Navigate to AI Asset Management > Images.

    3. On the Custom Image tab, click Register Image, and select Build New Image.

    4. Configure Basic Information:

    Register Image dialog - Build New Image

    Parameter

    Description

    Basic Information

    Image Type

    Currently, only Enterprise Edition images can be built. For more information, see What is Container Registry (ACR)?.

    Enterprise Edition Instance / Image Namespace / Image Repository / Custom Domain Name

    Select an existing instance, namespace, repository, and custom domain name, or go to the Container Registry console to create them.

    Note

    If you encounter a permission error, grant AliyunContainerRegistryReadOnlyAccess to your RAM user. For more information, see Manage RAM user permissions.

    Visibility

    • Visible to Me: Only you and workspace administrators can see this image.

    • Visible to Current Workspace: All workspace members can see this image.

    Chip Type

    Select CPU or GPU to match your target hardware.

    Runtime Information

    Resources

    Select compute resources for the build job. Choose higher specs if your Dockerfile includes compilation steps.

    VPC Configuration / Security Group

    Select the VPC bound to your Enterprise Edition instance and an appropriate security group.

    Note

    If your build job needs public network access (for example, to download dependencies), create an Internet NAT gateway, attach an EIP, and configure SNAT rules. For more information, see Use a dedicated gateway to improve public network access speed.

    Build Configuration

    Build Method

    • Based on Existing Image: Start from an official, custom, or third-party image. Install dependencies using pip2, pip3, yum, or apt. For private repositories, enter authentication credentials.

    • Based on Dockerfile: Write custom Dockerfile instructions. For syntax details, see Dockerfile reference.

    1. Configure Runtime Information as described in the table above.

    2. Configure Build Configuration and select your preferred build method.

    3. Click Confirm to start the build job.

    Monitor build jobs

    Track the progress and troubleshoot issues with your image build jobs.

    1. On the Custom Image tab, click View Jobs.

    2. Locate your build job and view its status.

      View Jobs interface showing build job list

    3. Click View Log to see build output and debug issues.

    4. Click View Monitoring to see resource utilization for the DLC job.

      Job details page with View Log and View Monitoring

    Use custom images

    After registration, your custom image is ready for training jobs.

    1. On the Custom Image tab, locate your image and copy its registry address.

      Custom Image tab showing registered images

    2. Use this address when creating training jobs. For more information, see Create a training job.

    References