Using the PPU PIP service-ZHENWU PPU Cloud Service(ppu)-阿里云帮助中心

This topic describes how to use the PPU SAIL PIP service (recommended) and the PPU PIP service provided by Alibaba Cloud.

Using the PPU SAIL PIP service (recommended)

Important

For PPU SDK 2.2.x and later, use the PPU SAIL PIP source.

Service description

The target source address (Index URL) is fixed: https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple.
When you install a package, the system automatically detects the SDK, CUDA, Torch, OS, and Python versions in the current environment and matches a suitable package. You can also use environment variables to control the compatibility detection strategy.

Configure the PIP source

Option 1: Temporary use (command-line parameters)

If you only need to use this source for a single installation, specify it with the -i or --index-url parameter. This approach does not change any system configuration.

pip install <package_name> -i https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple

For example, to install the torch library:

pip install torch -i https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple

Option 2: Global configuration (modify the configuration file)

This is the most common and recommended approach. After configuration, all pip install commands use this source by default.

Method 1: One-command configuration (recommended)
Run the following command in the terminal. pip writes it to the configuration file automatically.
```
pip config set global.index-url https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple
```
Method 2: Edit the configuration file manually
Locate or create the pip configuration file for your operating system, and add the following content.
```
[global]
index-url = https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple
```
The following table lists the pip configuration file paths for each operating system.
Operating system
Configuration file path
macOS / Linux
~/.config/pip/pip.conf or ~/.pip/pip.conf
Windows
%APPDATA%\pip\pip.ini
Example: C:\Users\<username>\AppData\Roaming\pip\pip.ini
Note
If the pip folder or configuration file does not exist, create it manually.

Option 3: Environment variable configuration

You can change the default pip behavior by setting environment variables. This approach is commonly used in CI/CD pipelines, such as Jenkins, GitLab CI, and GitHub Actions.

Linux / macOS

export PIP_INDEX_URL="https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple"

Add this command to ~/.bashrc or ~/.zshrc to make it take effect permanently.

Windows (CMD)

set PIP_INDEX_URL=https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple

Windows (PowerShell)

$env:PIP_INDEX_URL="https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple"

Verify the configuration

After configuration, run the following command to check the current pip configuration.

pip config list

The output should include the following content.

global.index-url='https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple'

You can also install a package in verbose mode and check the actual request URL in the logs.

pip install torch -v

Query packages

Query the packages supported by the source

The pip search command has been disabled in pip, so you cannot use pip to query which packages the source provides. As an alternative, visit the following address. Each link on the page represents a supported package.

https://pkg.flytiger-eco.com/artifactory/api/pypi/pypi_index/simple/

Note

For information about why the pip search command was disabled, see Deprecated methods.

Query the versions supported by a specific package

After you upgrade your local pip to version 21.2 or later, run the following command to query all published versions of a specific package.

pip index versions torch

The following is an example of the command output. Available versions lists the published versions. For compatibility details, see Compatibility below.

WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
torch (2.13.0+v0.1.0.ppu2.2.0)
Available versions: 2.13.0+v0.1.0.ppu2.2.0, 2.11.0+v0.2.0.ppu2.2.0, 2.11.0+v0.1.0.ppu2.1.1, 2.10.0+v0.2.0.ppu2.2.0, 2.10.0+v0.1.0.ppu2.1.1, 2.9.0+v0.2.0.ppu2.2.0, 2.9.0+v0.1.0.ppu2.1.1, 2.8.0+v0.2.0.ppu2.2.0, 2.8.0+v0.1.0.ppu2.1.1, 2.7.0+v0.2.0.ppu2.2.0, 2.7.0+v0.1.0.ppu2.1.1, 2.6.0+v0.2.0.ppu2.2.0, 2.6.0+v0.1.0.ppu2.1.1, 2.5.1+v0.1.0.ppu2.1.1, 2.4.0+v0.1.0.ppu2.1.1, 2.3.0+v0.1.0.ppu2.1.1, 2.1.2+v0.1.0.ppu2.1.1, 2.1.0+v0.1.0.ppu2.1.1, 2.0.1+v0.1.0.ppu2.1.1, 1.12.0+v0.1.0.ppu2.1.1, 1.8.0+v0.1.0.ppu2.1.1
  INSTALLED: 2.13.0+v0.1.0.ppu2.2.0
  LATEST:    2.13.0+v0.1.0.ppu2.2.0

Install packages

Package version number description

Take torch 2.10.0+v0.2.0.ppu2.2.0 as an example. The following table describes each field in the version number.

Field	Description
`2.10.0`	The community version number of the package.
`v0.2.0`	This indicates that SAIL has performed two rounds of optimization for Torch 2.10.0, and this package is the second optimized version.
`ppu2.2.0`	The PPU SDK version used for compilation, which is the SDK version that the package is compatible with by default.

Installation methods

Specify only the package name
```
pip install torch
```
This installs the latest version of torch. In the query example above, torch 2.13.0 is installed.
Warning
If the latest version has not been adapted and released for the SDK version in the current environment, the installation fails. In this case, specify an adapted version.
Specify the package name and version
```
pip install torch==2.10.0
```
This installs a torch 2.10.0 package that is compatible with the local SDK version. If multiple packages meet the criteria, the package with the higher minor version is installed.
Specify the package name and detailed version number
```
pip install torch==2.10.0+v0.1.0.ppu2.1.1
```
This installs the corresponding .whl package.
Warning
By default, a later SDK version can use .whl packages compiled with an earlier SDK version. If the local SDK version is earlier than 2.1.1, the installation fails.
Install a file directly
```
pip install https://pkg.flytiger-eco.com/artifactory/pypi_generic/torch/2.10.0+v0.2.0.ppu2.2.0/torch-2.10.0+cu130ubuntu2404oe-cp312-cp312-linux_x86_64.whl
```
If you have determined that the current package is the best choice, you can install it directly using the file URL.
Note
When you run the pip install torch==2.10.0 -v command, the -v parameter makes the installation log print the corresponding file URL after a successful installation.

Compatibility

Default compatibility rules

Compatibility rules for the SDK

Take torch==2.10.0+v0.1.0.ppu2.1.1 as an example. The version number indicates that the package was compiled with SDK 2.1.1:

When the SDK version in the environment is 2.1.1, the package is guaranteed to be compatible.
When the SDK version in the environment is later than 2.1.1, you can pull the package. This scenario has not been fully tested for compatibility. If you encounter issues, contact your account manager (BTE).
When the SDK version in the environment is earlier than 2.1.1, the package cannot be pulled under the default settings.

Compatibility rules for other environment factors

Compatible packages strictly match the detected environment factors (except the SDK version), including:

SDK version: controlled by the SAIL_PYPI_SDK_VERSION environment variable.
CUDA version: controlled by the CUDA_SDK_VER environment variable.
Torch version.
OS.
Python version.

Special compatibility rules

For some packages, SAIL has performed thorough compatibility testing, and a package may be compatible with some SDK versions but not others. Under the default settings, pip automatically identifies these compatibility rules based on the local environment.

Control compatibility with environment variables

Environment variable	Description	Configuration example
`SAIL_PYPI_SDK_VERSION`	Sets the SDK version that pip reads. This takes precedence over the directly detected SDK version.	`export SAIL_PYPI_SDK_VERSION=2.1.0`
`CUDA_SDK_VER`	Sets the CUDA version that pip reads. This takes precedence over the directly detected CUDA version.	`export CUDA_SDK_VER=cuda-12.8`
`SAIL_SDK_MATCH_STRATEGY`	When set to `off`, automatic compatibility detection is disabled, and pip installs the .whl package it matches directly.	`export SAIL_SDK_MATCH_STRATEGY=off`

After automatic compatibility detection is disabled, you can pull any .whl package by specifying its version number.

export SAIL_SDK_MATCH_STRATEGY=off
pip install torch==2.13.0+v0.1.0.ppu2.2.0

Note

This approach only disables automatic compatibility detection. Because CUDA and Torch versions are still required to obtain the .whl package URL, the installation still fails if the environment has no CUDA.

Download .whl packages in a CPU environment

Option 1: Download the .whl package directly.

wget https://pkg.flytiger-eco.com/artifactory/pypi_generic/torch/2.10.0+v0.2.0.ppu2.2.0/torch-2.10.0+cu130ubuntu2404oe-cp312-cp312-linux_x86_64.whl

Option 2: Set the environment variables, and then install.

export SAIL_SDK_MATCH_STRATEGY=off
export CUDA_SDK_VER=cuda-12.8
pip install torch==2.10.0
pip install apex

Using the PPU PIP service provided by Alibaba Cloud

Important

For PPU SDK 2.2.x and later, use the PPU SAIL PIP source.

Scenario description

The PIP service can be used within a VPC. Your PPU pods do not need public network access, which meets compliance and network control requirements.
You only need to configure one PIP source to install both PPU and CPU PIP packages in one place.
Package installation does not require manual authentication (consistent with the community experience).

Index URLs of the PPU PIP service provided by Alibaba Cloud

The following table lists the Index URLs of the PPU PIP service provided by Alibaba Cloud. Select the Index URL based on the PPU SDK version you use.

Mode

Index URL of the PPU PIP service provided by Alibaba Cloud

(Recommended) OS/CUDA Free mode Index URL

(Introduced in v1.7.x)

Fixed: https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/pypi_index/simple/

OS Free mode Index URL

(Introduced in v1.6.x)

Format: https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/<cuda-version>/simple/

Examples:

https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu128/simple/
https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu129/simple/

OS-bound Index URL

(<=v1.5.3)

Format：https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_<cuda-version>/simple/

Examples:

https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu128/simple/
https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu129/simple/

Note

In the table above, <cuda-version> is an enumerated value, such as cu128, cu129, cu126, cu124, and cu123. For the valid values, see PPU PIP packages.
During installation, OS/CUDA Free mode PIP packages automatically detect the OS, CUDA, Torch, and Python versions in the environment and match a suitable package.
OS Free mode PIP packages are compatible with different OS versions, and the source URL does not need to specify a particular OS.
The new OS/CUDA Free mode PIP packages can still be installed using the Index URLs of the previous OS Free mode (introduced in v1.6.x) and OS-bound mode (v1.5.3 and earlier).

PPU PIP package installation guide

The following example uses flash-attn==2.4.3+ppu1.5.2.ce to explain the naming rules for PPU PIP package installation commands:

Field component

2.4.3

+ppu1.5.2

.ce

Field description

Software version

Release version

ce/oe field

ce: open source (Community Edition)
oe: optimized for PPU (Optimized Edition)

The software version, release version, and ce/oe field of the flash-attn==2.4.3+ppu1.5.2.ce package can be omitted, so in theory you have four ways to install the software.

Important

Choose based on the specific package list and version information published on PIP List. Not every combination has a corresponding package.

pip install flash-attn==2.4.3+ppu1.5.2.ce 
pip install flash-attn==2.4.3+ppu1.5.2     # ce/oe field omitted: installs the "optimized" package by default; if unavailable, installs the "community" package
## The following two are recommended
pip install flash-attn==2.4.3              # Release version omitted: installs the latest compiled version of that version on the PIP source by default
pip install flash-attn                     # Software version omitted: installs the latest version by default

Usage examples

Container development environments (such as DinD and Buildah)

Set up the environment for your scenario and use the PIP service.

DinD scenario

Start the inner PPU container.

The following command uses a standard image as the base image.

id=$(docker run --network host -tid --privileged egslingjun-registry.cn-wulanchabu.cr.aliyuncs.com/egslingjun/inference-xpu-pytorch:26.01-v2.0.0-vllm0.12.0-torch2.8-cu129-20260127 bash)

Enter the inner PPU container.
```
docker exec -it $id bash
```
Install PIP packages using the PPU PIP service.
The following command uses the CUDA 12.9 (cu129) PPU PIP service to install torch==2.9.0 as an example.
```
pip install torch==2.9.0 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu129/simple/
```
For more container image development operations, see Best practices for developing PPU user container images.

Buildah scenario

Create a Dockerfile.

# Use a standard image as the base image
FROM egslingjun-registry.cn-wulanchabu.cr.aliyuncs.com/egslingjun/inference-xpu-pytorch:26.01-v2.0.0-vllm0.12.0-torch2.8-cu129-20260127

# Other Dockerfile steps omitted

# Example: install torch==2.9.0 using the CUDA 12.9 PPU PIP service
RUN pip install torch==2.9.0 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu129/simple/

Build the image using the buildah command.

buildah --storage-driver=overlay build --no-cache -t test:v1 .

View the built images.
```
buildah --storage-driver=overlay images
```

Standard PPU container environment

You can query and obtain the AI container images in Historical image versions and use them to start a PPU pod directly. The pod is suitable for one-off task environments. After the task is complete, the pod automatically exits, and changes to the container environment are not saved.

Install PIP packages using the PPU PIP service.
The following command uses the CUDA 12.9 (cu129) PPU PIP service to install torch==2.9.0 as an example.
```
pip install torch==2.9.0 -i https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/cu129/simple/
```
For more container image development operations, see Best practices for developing PPU user container images.

FAQ

PIP source hash value error

If you encounter the following PIP source hash value error, use the --no-cache option to resolve it.

# If a pip source hash value error occurs, add the --no-cache option
pip install --no-cache torch==2.1.2+ppu1.5.2

# Alternatively, clear all pip caches on the system before installing
pip cache purge
pip install torch==2.1.2+ppu1.5.2

No compatible package has been released for the current environment

The following is an example of the error. Contact your account manager (BTE) to request an additional release.

      Strategy return:
      No installation package compatible with the current environment
      python:cp312, platform:linux_x86_64, os:alios7u2, runtime_version:130
      version:0.5.12, framework:torch2.13.0, build version:0.5.12+v0.2.0.ppu2.2.0
      Contact FlyTiger to release the current configuration package if required.

strip_trailing_zero error

The following is an example of the error.

typeerror: canonicalize_version() got an unexpected keyword argument 'strip_trailing_zero'

This issue is caused by incompatibility with a later version of setuptools. Try downgrading setuptools to resolve it.

pip install setuptools==69.1.0

Error indicating that torch cannot be found

This error occurs in some environments with a later version of pip. A later version of pip uses an isolated build environment by default, and the torch version in the current environment cannot be read in the isolated environment. Add the --no-build-isolation installation parameter to resolve it.

pip install xxx --no-build-isolation

A compatible version exists, but installation fails

Take the package-demo package as an example. If a lower version compatible with the current environment has been released (for example, package-demo==1.0.0), pip install package-demo installs it normally because 1.0.0 is the highest version on the source and pip installs that version by default.

If later a package-demo==2.0.0 version is released but is not adapted to the current environment, pip install package-demo fails because pip pulls the latest version, 2.0.0, and that version has no package compatible with the current environment.

To avoid this situation, we strongly recommend that you pin the package version during installation. Then, even if an incompatible later version is released later, the installation still succeeds.

pip install package-demo==1.0.0

Appendix

Use and modify the PIP configuration file

The pip.config file of the PIP service provided by Alibaba Cloud works differently in different AI container image versions. Configure it as needed for the image version you use.

Use the PIP service in AI container images up to 25.07 (inclusive)

Note

AI container images up to 25.07 (inclusive) have the PIP_INDEX_URL=http://mirrors.cloud.aliyuncs.com/pypi/simple/ environment variable built in. By default, this variable overrides the new settings in the pip.config file. Note the following:

If you omit the -i <index-url> option and run the pip install command, the environment variable overrides the settings in the pip.config file, causing an incorrect Index URL to be used. To use the PIP service provided by Alibaba Cloud properly, run the unset PIP_INDEX_URL or export PIP_INDEX_URL= command to disable the environment variable.
If you explicitly specify the -i <index-url> option when running the pip install command, it is not affected.

The PIP service provided by Alibaba Cloud supports one-stop installation of PPU-related CUDA PIP packages and non-CUDA PIP packages from the PyPI community. That is, you need only one PIP source to install all PIP packages.

The following is the recommended configuration file, which can replace the default configuration file in the image. With this configuration file, you do not need to add the -i <index-url> option when installing PIP packages.

Note

In the following configuration file, <cuda-version> must be configured based on the CUDA version of the container image you use (you can query it with the nvcc --version command). Valid values include cu126, cu124, and cu123, among others.

[global]
index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_<cuda-version>/simple/
# eg: index-url = https://aiext-pypi.mirrors.aliyuncs.com/pg1-pip/ubuntu_cu126/simple/

[install]
trusted-host = aiext-pypi.mirrors.aliyuncs.com

Use the PIP service in AI container images 25.08 and later

AI container images 25.08 and later already include the configuration file for the PIP service provided by Alibaba Cloud, and it is enabled by default, so no additional operations are usually required. If you have modified the pip.config symbolic link, you can restore the PIP service configuration provided by Alibaba Cloud using the following command.

# Use the PIP service provided by Alibaba Cloud in AI container images 25.08 and later (default configuration in the image; no action required)
# If the ~/.pip/pip.config symbolic link already points to another configuration file, run rm ~/.pip/pip.config to remove it first, and then recreate it
ln -s ~/.pip/pip.config.aiext-pypi ~/.pip/pip.config