Use the PPU pip service on ACS
This topic describes how to use the PTG PPU pip service and the Alibaba Cloud PPU pip service on ACS. The PTG PPU pip service requires you to apply for an authentication account and password. Packages are installed over the public network, and you must explicitly provide the credentials during installation. The Alibaba Cloud PPU pip service supports credential-free access within a VPC, so your Pods do not need internet access. This service requires some prerequisite configuration. Both services offer the same pip packages, which are identical in type, number, and name. You can choose the service that best fits your needs.
Use the Alibaba Cloud PPU pip service
Use cases
Use the pip service within a VPC. This eliminates the need for public network access for your Pods, helping you meet compliance and network control requirements.
Install both XPU and CPU pip packages by configuring a single pip source.
Install packages without manual authentication, which aligns with the standard community experience.
After completing the necessary configuration, you can use this service with all ACS PPUs.
Comparison with the PTG PPU pip service
PTG PPU pip service | Alibaba Cloud PPU pip service | |
Pip source index URL | An index URL in the format of | An index URL in the format of For detailed index URL information and mapping rules, see Alibaba Cloud PPU pip service index URLs. |
Pip source authentication | Requires explicit authentication (apply as needed). | Credential-free (available after configuration). |
Usage scope | Users who have applied for an account and password. | All ACS PPU users (requires configuration). |
Access method | Internet access | Internet access, access within a VPC |
Pre-use configuration | No additional configuration required. | Requires preliminary configuration. |
Package usage | Package names, number, and installation methods are the same. | Package names, number, and installation methods are the same (only the pip source index URL needs to be replaced). |
Notes | This service may be discontinued in the future. |
How to use
Enable credential-free pip authorization
Prerequisites: Before you start, check the official PPU-PIP package list provided on the Alibaba Cloud PPU website. You can only install packages from this list. For CUDA-related pip packages not on the list, we recommend building from source. For detailed steps, see Build pip packages from source.
Resources and billing: The credential-free authorization for pip feature deploys a three-replica stateless workload named
ack-pod-identity-webhookin your cluster. The system resource requests (resources.requests) for each Pod are 100m CPU and 100 Mi Memory. You are billed for the resources used by these three Pods according to the ACS Billing Guide. To ensure that the feature functions correctly, do not remove this workload.
You authorize the credential-free pip service for ACS PPU instances on a per-cluster basis. In the ACS console, navigate to the Cluster List page, find your target cluster, and click its name to go to the Cluster Information page. On the Basic Information tab, locate the Security and Audit panel and follow the instructions to enable Credential-free authorization for pip.
NoteEach time you add a credential-free authorization, a Service Account is generated for a specific cluster namespace. All Pods within that namespace can use it. To grant this access to Pods in other namespaces, you must add a new authorization for each.
Click Add Authorization and select the desired namespace to verify that the authorization was added and to view existing Service Accounts.
The underlying implementation of credential-free authorization for pip is based on Using RRSA to configure RAM permissions for a ServiceAccount to isolate Pod permissions.
Generate the authorization URL and complete the authorization process in a new browser tab.

Note the Service Account name for the ACS cluster. You will need it for subsequent configuration.

After you enable credential-free authorization for the cluster, DinD, Buildah, and standard PPU Pods in the corresponding namespaces meet the prerequisites for credential-free pip access.
Use the PPU pip service
Container development environments
Add the credential-free authorization field to the YAML file.
Modify the YAML file used to create the DinD or Buildah Pod in Best practices for developing container images for ACS PPU users by adding the
spec.serviceAccountNamefield.
Set up the environment and use the pip service based on your scenario.
DinD
When you start the inner PPU container, mount the necessary environment variables and files for credential-free authentication.
# To use the pip service provided by PTG id=$(docker run --network host -tid --privileged {ppu-image-uri} bash) # Modify the container startup command as follows: add four ALIBABA_CLOUD* environment variables and one file mount. # To use the pip service provided by Alibaba Cloud id=$(docker run --network host -tid --privileged \ -e ALIBABA_CLOUD_OIDC_PROVIDER_ARN=$ALIBABA_CLOUD_OIDC_PROVIDER_ARN \ -e ALIBABA_CLOUD_ROLE_ARN=$ALIBABA_CLOUD_ROLE_ARN \ -e ALIBABA_CLOUD_OIDC_TOKEN_FILE=$ALIBABA_CLOUD_OIDC_TOKEN_FILE \ -e ALIBABA_CLOUD_STS_ENDPOINT=$ALIBABA_CLOUD_STS_ENDPOINT \ -v /var/run/secrets/ack.alibabacloud.com/rrsa-tokens/:/var/run/secrets/ack.alibabacloud.com/rrsa-tokens/ \ {ppu-image-uri} bash)Install the credential-free plugin inside the inner PPU container. You can then use the pip service without credentials. Compared to the pip service provided by PTG, you only need to replace the index URL in the installation command.
# Other Linux package installation steps are omitted. # The following steps demonstrate how to install pip packages using the service provided by Alibaba Cloud. ## 1. First, install the credential-free plugin aiext-pypi-plugin. pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com ## 2. You can then install the required pip wheel packages without credentials. For example: pip install torch==2.5.1 vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/ ## 3. After the pip installation is complete, we recommend cleaning up the environment. pip uninstall -y aiext-pypi-plugin rm ~/.netrc # Clean up as needed, or edit the file to remove only the content related to machine aiext-pypi.mirrors.aliyuncs.com.
Buildah
Make the necessary modifications to your Dockerfile. Install the credential-free plugin, and then you can use the pip service without credentials. Compared to the pip service provided by PTG, you only need to replace the index URL in the installation command.
# If you use a standard image provided by ACS FROM egslingjun-registry.cn-wulanchabu.cr.aliyuncs.com/egslingjun/{image:tag} # Other Dockerfile steps are omitted. # The following steps demonstrate how to install pip packages using the service provided by Alibaba Cloud. ## 1. Set the credential-free related environment variables. ARG ALIBABA_CLOUD_STS_ENDPOINT ARG ALIBABA_CLOUD_OIDC_PROVIDER_ARN ARG ALIBABA_CLOUD_ROLE_ARN ENV ALIBABA_CLOUD_STS_ENDPOINT=${ALIBABA_CLOUD_STS_ENDPOINT} ENV ALIBABA_CLOUD_OIDC_PROVIDER_ARN=${ALIBABA_CLOUD_OIDC_PROVIDER_ARN} ENV ALIBABA_CLOUD_ROLE_ARN=${ALIBABA_CLOUD_ROLE_ARN} ENV ALIBABA_CLOUD_OIDC_TOKEN_FILE=/mount/rrsa-tokens/token ## 2. Install the credential-free plugin aiext-pypi-plugin. Note: The plugin currently does not support requests executed with 'python -m pip'. RUN pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com ## 3. Add the --mount option before each 'pip install' command. For example: RUN --mount=type=bind,source=/var/run/secrets/ack.alibabacloud.com/rrsa-tokens,target=/mount/rrsa-tokens \ pip install torch==2.5.1 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/ RUN --mount=type=bind,source=/var/run/secrets/ack.alibabacloud.com/rrsa-tokens,target=/mount/rrsa-tokens \ pip install vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/ ## 4. After the pip installation is complete, we recommend cleaning up the environment. RUN pip uninstall -y aiext-pypi-pluginAdd the four
ALIBABA_CLOUD*build arguments to the buildah build command in the Buildah Pod. Modify the command as follows:# To use the pip service provided by PTG buildah --storage-driver=overlay build --no-cache -t test:v1 . # Modify the command as follows, adding four ALIBABA_CLOUD* build arguments: # To use the pip service provided by Alibaba Cloud buildah --storage-driver=overlay build --no-cache \ --build-arg ALIBABA_CLOUD_OIDC_PROVIDER_ARN=$ALIBABA_CLOUD_OIDC_PROVIDER_ARN \ --build-arg ALIBABA_CLOUD_ROLE_ARN=$ALIBABA_CLOUD_ROLE_ARN \ --build-arg ALIBABA_CLOUD_STS_ENDPOINT=$ALIBABA_CLOUD_STS_ENDPOINT \ -t demo:v1 .
Standard PPU containers
You can find and use an AI container image from the ACS Container Image Release Notes to directly launch a PPU container. This type of container is suitable for one-time task environments. After the task is complete, the container Pod exits automatically, and any changes to its environment are lost.
Add the credential-free authorization field to the YAML file.
Modify the YAML file used to create the PPU Pod by adding the
spec.serviceAccountNamefield.
Set up the environment and use the pip service inside the standard PPU container.
# 1. First, install the credential-free plugin aiext-pypi-plugin. Note: The plugin currently does not support requests executed with 'python -m pip'. pip install aiext-pypi-plugin -i http://mirrors.cloud.aliyuncs.com/aiext-pypi/aiext-pypi-plugin/simple --trusted-host mirrors.cloud.aliyuncs.com # 2. You can then install the required pip wheel packages without credentials. For example: pip install torch==2.5.1 vllm==0.7.3 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu123/simple/
Alibaba Cloud PPU pip service index URLs
The index URLs for the Alibaba Cloud PPU pip service map directly to those of the PTG PPU pip service. The mapping rules are shown in the table below.
Both sets of index URLs provide identical package content.
Alibaba Cloud index URL | PTG index URL | |
OS-bound index URL (v1.5.3 and earlier) | Format: Example:
| Format: Example:
|
OS-free mode index URL (Introduced in v1.6.x) | Format: Example:
| Format: Example:
|
OS/CUDA-free mode index URL (Introduced in v1.7.x) | Fixed URL: | Fixed URL: |
Use the PTG PPU pip service
Use cases
The PTG pip service can only be accessed over the public network.
Before use, you must request authentication credentials for the pip source from your PDSA.
PPU pip
The PPU pip source provides frameworks that are suitable for PPU products and open-source libraries that are recompiled based on the PPU SDK, which helps you quickly set up a production environment. If a package you need is not available from the PPU pip source, it is pulled from the official PyPI source by default.
The PPU-PIP package list is updated monthly. Optimized Edition packages contain code that has been modified and performance-tuned for PPU. Community Edition packages are open-source libraries and frameworks that are compiled on the PPU SDK.
PPU pip naming conventions
Index URLs for v1.5.3 and earlier
For v1.5.3 and earlier, the naming convention for the Python Package Index base URL of the PPU pip source is: {index-prefix}_{os}_{cuda}_{index-suffix}. The fields are described below:
Component | Value | Description |
index-perfix component | Fixed value: | |
os component | Enumerated values: | Only Ubuntu images are available in ACS scenarios. |
cuda component | Enumerated values: | |
index-suffix component | Fixed value: |
The following are examples of complete Python Package Index base URLs:
https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu124_index/simple/
OS-free mode index URLs (v1.6.x)
For the OS-free mode introduced in v1.6.x, the naming convention for the Python Package Index base URL of the PPU pip source is: {os-free-index-prefix}{cuda}{os-free-index-suffix}. The fields are described below:
Component | Value |
os-free-index-prefix component | Fixed value: |
cuda component | Enumerated values: |
os-free-index-suffix component | Fixed value: |
Packages in OS-free mode are OS-agnostic, so you do not need to specify an OS in the source address.
You can still install the new OS-free mode packages by using the older, OS-bound index URLs.
The following are examples of complete OS-free Python Package Index base URLs:
https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu128_index/simple/
https://art-pub.eng.t-head.cn/artifactory/api/pypi/cu126_index/simple/
OS/CUDA-free mode index URLs (v1.7.x)
For the OS/CUDA-free mode introduced in v1.7.x, the Python Package Index base URL for the PPU pip source is fixed as:
https://art-pub.eng.t-head.cn/artifactory/api/pypi/pypi_index/simple/During installation, OS/CUDA-free mode packages automatically detect the environment's OS, CUDA, Torch, and Python versions to select the appropriate package.
The new OS/CUDA-free mode pip packages can still be installed by using the index URLs from the previous OS-free mode (introduced in v1.6.x) and OS-bound mode (v1.5.3 and earlier).
PPU pip package installation
The following example, flash-attn==2.4.3+ppu1.5.2.ce, explains the PPU pip package naming convention:
Component | 2.4.3 | +ppu1.5.2 | .ce |
Field description | Software version | Release version | ce/oe field
|
For the flash-attn==2.4.3+ppu1.5.2.ce package, you can omit the software version, release version, and ce/oe fields. This allows for four theoretical installation methods.
You must choose based on the specific list and version information that is published in the pip list, as not every combination corresponds to an available package.
pip install flash-attn==2.4.3+ppu1.5.2.ce
pip install flash-attn==2.4.3+ppu1.5.2 # If ce/oe is omitted, pip tries to install the Optimized Edition, then falls back to the Community Edition.
## The following two methods are recommended:
pip install flash-attn==2.4.3 # Release version omitted: By default, the latest build of this version on the pip source is installed.
pip install flash-attn # Software version omitted: By default, the latest version is installed.Examples
The following are complete examples of pip package installation commands:
pip install sglang==0.4.6.post1+ppu1.5.1 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
pip install vllm==0.6.6.post1+ppu1.5.1 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
pip install mmdet3d==1.4.0 -i https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/If you are using the Alibaba Cloud PPU pip service, you only need to replace the index URL in the commands above with https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/.
Troubleshooting
If you encounter a pip source hash value error, use the --no-cache option to resolve the issue.

# If you encounter a pip source hash mismatch error, add the --no-cache-dir option.
pip install --no-cache-dir torch==2.1.2+ppu1.5.2
# Alternatively, clear the entire pip cache on your system before you reinstall.
pip cache purge
pip install torch==2.1.2+ppu1.5.2Appendix
Pip configuration file
The pip.config file requires different configurations for the Alibaba Cloud and PTG pip services. Use the configuration that matches your service.
AI container images (v25.07 and earlier)
AI container images v25.07 and earlier have a built-in PIP_INDEX_URL=http://mirrors.cloud.aliyuncs.com/pypi/simple/ environment variable. By default, this overrides any new settings in the pip.config file. Keep the following in mind:
If you run the
pip installcommand without the-i <index-url>option, an environment variable overrides the settings in thepip.configconfiguration file and causes an incorrect Index URL to be used. To ensure that you can properly use the pip service provided by Alibaba Cloud and the pip service provided by PTG, you need to run theunset PIP_INDEX_URLorexport PIP_INDEX_URL=command to disable this environment variable.If you explicitly specify the
-i <index-url>option when you run thepip installcommand, the operation is not affected.
Alibaba Cloud pip service
The Alibaba Cloud pip service provides a one-stop solution for installing PPU-related CUDA pip packages and non-CUDA pip packages from the PyPI community. Before you begin, you must complete the "Enable credential-free authorization for pip" setup as described in the previous sections. This allows you to install all pip packages from a single pip source.
The following is the recommended configuration file for the pip service provided by Alibaba Cloud. You can use it to replace the default configuration file for the image. This allows you to install pip packages without adding the -i <index-url> option.
Set <cuda-version> in the configuration file to the CUDA version of your container image, which you can find by running the nvcc --version command. Valid values include cu126, cu124, and cu123.
[global]
index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_<cuda-version>/simple/
# For example: index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/
[install]
trusted-host = aiext-pypi.mirrors.aliyuncs.comPTG pip service
The PTG pip service provides a one-stop solution for installing PPU-related CUDA pip packages and non-CUDA pip packages from the PyPI community. Before you begin, you must obtain the account and password for the PTG pip service from your PDSA. This allows you to install all pip packages from a single pip source.
The following is the recommended configuration file for the pip service provided by PTG, which can replace the default configuration file in an image. With this configuration file, you can install pip packages without adding the -i <index-url> option.
In the following configuration file, set <cuda-version> to the CUDA version of your container image, which you can check by running the nvcc --version command. Valid values include cu126, cu124, and cu123.
[global]
index-url = https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_<cuda-version>_index/simple/
# For example: index-url = https://art-pub.eng.t-head.cn/artifactory/api/pypi/ptgai-pypi_ppu_ubuntu_cu126_index/simple/
[install]
trusted-host = art-pub.eng.t-head.cn mirrors.cloud.aliyuncs.comAI container images (v25.08 and later)
AI container images v25.08 and later have built-in configuration files for both the Alibaba Cloud pip service and the PTG pip service. You can switch between configurations by modifying a symbolic link.
# Use the pip service provided by Alibaba Cloud in AI container images v25.08 and later (this is the default configuration in the image, so no action is needed).
## If you are switching from the PTG service to the Alibaba Cloud service, you must first remove the pip.config symbolic link (rm ~/.pip/pip.config).
ln -s ~/.pip/pip.config.aiext-pypi ~/.pip/pip.config
# Use the pip service provided by PTG in AI container images v25.08 and later.
ln -s ~/.pip/pip.config.art-pub ~/.pip/pip.configConfigure a .netrc file for automatic authentication
To avoid the inconvenience of entering your PTG pip credentials for each installation, you can use a .netrc file for automatic authentication.
# PIP .netrc
cat > ~/.netrc << EOF
machine art-pub.eng.t-head.cn
login <pip-username>
password <pip-passwd>
EOFAI container images v25.07 and earlier use a mix of two sources:
mirrors.cloud.aliyuncs.com(which does not require credentials and is used for non-CUDA pip packages) andart-pub.eng.t-head.cn(which requires credentials and is used for PPU versions of CUDA-related pip packages). You can continue to use them as before or modify the configuration as recommended in this document.AI container images from version 25.08 onward include two built-in
pip.configconfiguration files. You can switch between these files based on the specific pip service that you use.
Because the ~/.netrc file contains your username and password in plain text, set its permissions to 600 (read/write for owner only). We also recommend that you delete this file after use.