migration-ascend-torchnpu-skills-environment-setup

Skill: Ascend NPU Environment Setup

You are an engineer focused on Ascend NPU environment configuration. This Skill provides a complete procedure from driver installation to Python environment configuration.

<version_notice> The version compatibility information in this Skill is based on the latest data available at the time of writing. The Ascend software stack iterates quickly; when new versions are released, you MUST refer to the version compatibility table published on the official Ascend website:

torch_npu version compatibility table:https://gitcode.com/Ascend/pytorch
CANN version notes (including HDK version compatibility):https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/releasenote/release-notes.md
CANN Installation Guide:https://www.hiascend.com/document/detail/zh/canncommercial/
Ascend driver download:https://www.hiascend.com/developer/download/community
Ascend image repository:https://www.hiascend.com/developer/ascendhub

⚠ Versions will continue to be updated. You MUST access the official website links above in real time to obtain the latest version compatibility information; do not rely on the fixed version information in this Skill. Each time a migration task is performed, you should first consult the official documentation to obtain the latest version information, and fall back to the reference data in this Skill only when the official website cannot be accessed. </version_notice>

I. Version Compatibility Matrix

1.1 Core Component Version Correspondence

The following data comes from the official torch_npu repository (gitcode.com/Ascend/pytorch) and is only a snapshot at the time of writing. For new versions, please consult the official documentation.

CANN Version	PyTorch Version	torch_npu Version	Python Version	Notes
CANN 9.0.0	2.10.0	2.10.0	3.9-3.13	Latest version, supports Python 3.13
CANN 9.0.0	2.9.0	2.9.0.post2	3.9-3.12
CANN 9.0.0	2.8.0	2.8.0.post2	3.9-3.12
CANN 9.0.0	2.7.1	2.7.1.post3	3.9-3.11
CANN 8.5.2	2.9.0	2.9.0.post1	3.9-3.12
CANN 8.5.2	2.8.0	2.8.0.post1	3.9-3.11
CANN 8.5.2	2.7.1	2.7.1.post2	3.9-3.11
CANN 8.5.2	2.6.0	2.6.0.post6	3.9-3.11
CANN 8.5.1	2.9.0	2.9.0.post1	3.9-3.12
CANN 8.5.1	2.8.0	2.8.0.post1	3.9-3.11
CANN 8.5.1	2.7.1	2.7.1.post2	3.9-3.11
CANN 8.5.1	2.6.0	2.6.0.post6	3.9-3.11
CANN 8.5.0	2.9.0	2.9.0	3.9-3.12
CANN 8.5.0	2.8.0	2.8.0	3.9-3.11
CANN 8.5.0	2.7.1	2.7.1	3.9-3.11
CANN 8.5.0	2.6.0	2.6.0.post5	3.9-3.11
CANN 8.3.RC1	2.8.0	2.8.0	3.9-3.11
CANN 8.3.RC1	2.7.1	2.7.1	3.9-3.11
CANN 8.3.RC1	2.6.0	2.6.0.post3	3.9-3.11
CANN 8.2.RC1	2.6.0	2.6.0	3.9-3.11
CANN 8.2.RC1	2.5.1	2.5.1.post1	3.9-3.11
CANN 8.2.RC1	2.1.0	2.1.0.post13	3.8-3.11
CANN 8.1.RC1	2.5.1	2.5.1	3.9-3.11
CANN 8.1.RC1	2.4.0	2.4.0.post4	3.8-3.11
CANN 8.1.RC1	2.3.1	2.3.1.post6	3.8-3.11
CANN 8.1.RC1	2.1.0	2.1.0.post12	3.8-3.11
CANN 8.0.0	2.4.0	2.4.0.post2	3.8-3.11
CANN 8.0.0	2.3.1	2.3.1.post4	3.8-3.11
CANN 8.0.0	2.1.0	2.1.0.post10	3.8-3.11
CANN 7.0.0	2.1.0	2.1.0	3.8-3.10
CANN 7.0.0	2.0.1	2.0.1.post1	3.7-3.10

Minor Version Iteration Notes: In actual use, the CANN version number may have minor iterations (e.g., CANN 9.0.0 → CANN 9.0.1). Such minor version iterations usually maintain compatibility with the major version, and compatibility can be determined according to the major version (e.g., 9.0.0). However, you MUST verify actual usability after installation via torch.npu.is_available() .

1.1b CANN and Ascend HDK (Driver Firmware) Version Correspondence

The following data comes from the release notes of each CANN community edition (hiascend.com) and is only a snapshot at the time of writing.Versions are continuously updated. You MUST consult the official website in real time to obtain the latest correspondence.： https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/releasenote/release-notes.md

CANN Version	Compatible Ascend HDK Version	Notes
CANN 9.0.0	26.0.RC1 / 25.5.2 / 25.5.1	Latest version
CANN 8.5.2	25.5.x	—
CANN 8.5.1	25.5.x	—
CANN 8.5.0	25.5.x	—
CANN 8.3.RC1	25.x.x	—
CANN 8.2.RC1	25.2.0	—
CANN 8.1.RC1	24.x.x	—
CANN 8.0.0	24.x.x	—
CANN 7.0.0	23.x.x	—

Notes：

The Ascend HDK version number is the Ascend driver firmware version number. The driver installation package file name format is Ascend-hdk-{HDK版本}-npu-driver_linux-{arch}.run

26.0.RC1 , where RC stands for Release Candidate

The same CANN version may be compatible with multiple HDK versions; refer to the compatibility information in the official release notes.

Compatibility between HDK versions and CANN versions is unidirectional: you must first determine the CANN version, then determine the compatible HDK version.

⚠ Versions will be updated. The table above is for reference only. You MUST check the official website in real time: By visiting the release notes page for the corresponding CANN version (replace the version number in the URL with the target version), you can find the exact compatible HDK version for that version.

1.2 Version Selection Principles

Determine the PyTorch version used by the original project
Check whether that version is in the Ascend support list
If compatible: keep the original project's PyTorch version and find the corresponding torch_npu version
If not compatible: use the latest PyTorch version supported by Ascend and find the corresponding torch_npu version
Find the corresponding CANN version based on the torch_npu version
Find the corresponding Ascend driver version based on the CANN version (see 1.1b CANN and Ascend HDK Version Correspondence and the matching HDK version in the CANN version description,MUST consult the official website in real time to obtain the latest compatibility mapping）
When there is no mandatory version requirement: MUST consult the latest version compatibility mapping, and prefer the latest version to obtain better operator support and performance optimization

1.3 Version selection example


场景：原项目使用 PyTorch 2.1.0
1. 查表：PyTorch 2.1.0 在多个CANN版本中均有支持
2. 选择策略：选择最新的CANN版本（8.2.RC1），对应的torch_npu为 2.1.0.post13
3. 查CANN-HDK对应关系：CANN 8.2.RC1 配套 Ascend HDK 25.2.0（见 1.1b 节表）
4. 确认驱动：需要安装 25.2.0 版本的昇腾驱动

场景：原项目使用 PyTorch 2.9.0
1. 查表：PyTorch 2.9.0 在 CANN 9.0.0/8.5.2/8.5.1/8.5.0 中均有支持
2. 选择策略：选择最新的CANN版本（9.0.0），对应的torch_npu为 2.9.0.post2
3. 查CANN-HDK对应关系：CANN 9.0.0 配套 Ascend HDK 26.0.RC1 / 25.5.2 / 25.5.1（见 1.1b 节表）
4. 确认驱动：需要安装 26.0.RC1 或 25.5.x 版本的昇腾驱动

场景：原项目使用 PyTorch 2.6.0
1. 查表：PyTorch 2.6.0 在 CANN 8.5.2/8.5.1/8.5.0/8.3.RC1/8.2.RC1 中均有支持
2. 选择策略：选择最新的CANN版本（8.5.2），对应的torch_npu为 2.6.0.post6
3. 查CANN-HDK对应关系：CANN 8.5.2 配套 Ascend HDK 25.5.x（见 1.1b 节表）
4. 确认驱动：需要安装 25.5.x 版本的昇腾驱动

II. Environment setup (Docker image method preferred)

MUST prioritize using the Docker image method to set up the environment. Ascend official images have already integrated software packages and system dependencies such as the CANN toolkit, kernels, and NNAL, which can greatly reduce the workload and error probability of manual installation. It is recommended to use the latest version of the CANN image as the base for setup.

2.1 Image selection

Select an image from the Ascend image repository:https://www.hiascend.com/developer/ascendhub

CANN base image(recommended, most flexible):

Image repository address:swr.cn-south-1.myhuaweicloud.com/ascendhub/cann

For specific Tags, please refer to the following official channels (Tags are continuously updated with CANN versions):

Ascend image repository:https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884

Dockerfile and Tag list:https://github.com/Ascend/cann-container-image/tree/main/cann

Tag naming rules:{CANN版本}-{芯片型号}-{OS}-py{Python版本}

The image has already integrated the Toolkit development suite package, Kernels operator package, and NNAL acceleration library, so no additional installation is required.

Example (using a Tag that could be found at the time of writing as an example; for new versions, please refer to the above official channels):

Tag component	Optional values	Description
CANN version	`8.5.0`、`8.1.rc1`、`9.0.0` etc.	Select a CANN version that matches torch_npu
Chip model	`910b`、`910c`、`310p`、`910`、`950`	910C corresponds to the A3 series; for others, please refer to the Ascend official website
OS	`ubuntu22.04`、`openeuler24.03`	It is recommended to select the Ubuntu version
Python version	`py3.10`、`py3.11`	Select a Python version that matches the project

For the mapping between chip models and product series, please refer to the Ascend official documentation; do not infer it yourself

2.2 Pull the image

# 根据实际需求替换Tag，示例：CANN 8.5.0 + 910B + Ubuntu22.04 + Python3.10
# 具体Tag请查阅：https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884

# ARM架构（鲲鹏，推荐）
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10

# x86_64架构
docker pull --platform=amd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-910b-ubuntu22.04-py3.10

2.3 Start the container

The host MUST have the Ascend driver and firmware installed, and the Docker version must be >= 1.11.2.

# 查看镜像ID
docker images | grep ascendhub/cann

# 启动容器（MUST挂载NPU设备相关路径）
# 参考官方镜像说明：https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884
docker run --name npu_dev -dit --privileged --net=host --shm-size=500g \
  -w /home \
  --device=/dev/davinci0 \
  --device=/dev/davinci1 \
  --device=/dev/davinci2 \
  --device=/dev/davinci3 \
  --device=/dev/davinci4 \
  --device=/dev/davinci5 \
  --device=/dev/davinci6 \
  --device=/dev/davinci7 \
  --device=/dev/davinci_manager \
  --device=/dev/devmm_svm \
  --device=/dev/hisi_hdc \
  -v /usr/local/dcmi:/usr/local/dcmi \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
  -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
  -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
  -v /etc/ascend_install.info:/etc/ascend_install.info \
  -v /home:/home \
  -v /data:/data \
  -v /usr/share/zoneinfo/Asia/Shanghai:/etc/localtime \
  {镜像ID} \
  bash

Device mounting parameter description：

Parameter	Description
`--privileged`	Enable privileged mode to ensure full availability of NPU devices
`--device=/dev/davinci0~7`	Map all NPU cards (davinci0~davinci7)
`--device=/dev/davinci_manager`	Map the NPU device management interface
`--device=/dev/devmm_svm`	Map the device memory management interface
`--device=/dev/hisi_hdc`	Map the communication interface between the host and the device
`-v /usr/local/dcmi`	Mount DCMI tools and libraries
`-v /usr/local/Ascend/driver/lib64/`	Mount driver libraries
`-v /usr/local/Ascend/driver/version.info`	Mount driver version information
`-v /etc/ascend_install.info`	Mount driver installation information

2.4 Environment configuration inside the container

It is not recommended to use conda or venv inside the container; just use pip to manage the Python environment directly to avoid conflicts with the existing environment in the container.

# 先启动容器（后台运行）
docker start npu_dev

# 再进入容器
docker exec -it npu_dev bash

# 配置CANN环境变量（镜像内已安装CANN）
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 配置NNAL环境变量（CANN 8.1.RC1及以后版本需要）
source /usr/local/Ascend/nnal/atb/set_env.sh

# 安装PyTorch和torch_npu
# 优先从官方安装指南获取对应版本的下载链接
# 官方安装指南（MUST实时查阅昇腾官网最新版本文档，以下链接仅供参考）：
# 昇腾官网 → 文档 → PyTorch框架适配 → 软件安装指南 → 安装 → 使用二进制包安装
# 参考链接：https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md
# 根据目标PyTorch版本、架构(aarch64/x86_64)、Python版本，从上述文档查找对应的wget下载链接

# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：PyTorch 2.6.0 + aarch64 + Python 3.10 + CANN 8.5.0
pip install pyyaml setuptools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
wget https://download.pytorch.org/whl/cpu/torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
wget https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

# 方式2：pip直接安装（备选，网络通畅时使用）
# aarch64架构
# pip install torch==2.6.0
# x86_64架构
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
# pip install torch-npu==2.6.0.post5

# 验证
python -c "import torch; import torch_npu; print(torch.npu.is_available())"

2.5 Common container issues

Issue: The container exits immediately after startup → Use the -it parameter to start in interactive mode, or use docker start to restart a stopped container
Issue: Inside the container, npu-smi info produces no output → Check whether the host driver is installed, and check whether --device=/dev/davinci_manager has been added
Issue: Inside the container, torch.npu.is_available() returns False → Check whether the driver libraries are mounted correctly:ls /usr/local/Ascend/driver/lib64/

III. Manual installation method (alternative)

Use manual installation only when Docker is unavailable. Manual installation requires completing the following steps in order: driver installation → CANN installation → Python environment configuration.

3.1 Ascend Driver Installation

Check the hardware environment

npu-smi info
uname -m
# aarch64 = ARM架构（鲲鹏）
# x86_64 = x86架构

Install the driver

For a first-time installation, follow the order "driver > firmware"; for an overwrite installation, follow the order "firmware > driver".

# 1. 创建驱动运行用户（如尚未创建）
groupadd HwHiAiUser
useradd -g HwHiAiUser -d /home/HwHiAiUser -m HwHiAiUser -s /bin/bash

# 2. 下载对应版本的驱动包
# https://www.hiascend.com/developer/download/community

# 3. 安装驱动（需要root权限）
# 根据CANN版本选择对应的驱动版本，查阅 1.1b CANN与Ascend HDK版本对应关系 和CANN版本说明中的配套HDK版本
chmod +x Ascend-hdk-xxx-npu-driver_linux-aarch64.run
./Ascend-hdk-xxx-npu-driver_linux-aarch64.run --full --install-for-all

# 4. 安装固件
chmod +x Ascend-hdk-xxx-npu-firmware_linux-aarch64.run
./Ascend-hdk-xxx-npu-firmware_linux-aarch64.run --full

# 5. 重启系统
reboot

# 6. 验证安装
npu-smi info

Common Driver Issues

Issue：npu-smi info No output → Check whether the driver was installed successfully, and check whether the /usr/local/Ascend/driver directory exists
Issue: Insufficient permissions to access the NPU → Add the current user to the HwHiAiUser group:usermod -aG HwHiAiUser $USER
Issue: The driver is unavailable after a kernel upgrade → Disable automatic kernel updates:apt-mark hold linux-image-generic linux-headers-generic

3.2 CANN Software Stack Installation

Install system dependencies

# Ubuntu/Debian
apt-get update
apt-get install -y gcc g++ make cmake zlib1g zlib1g-dev openssl libsqlite3-dev libssl-dev libffi-dev unzip pciutils net-tools libblas-dev gfortran libblas3

# openEuler/EulerOS
yum install -y gcc gcc-c++ make cmake zlib zlib-devel openssl-devel sqlite-devel libffi-devel unzip pciutils net-tools blas-devel gfortran

Install the CANN toolkit

Before installing the toolkit, ensure that the installation directory has more than 9G of available space. You MUST install the toolkit before installing the kernels.

# 下载CANN toolkit
# https://www.hiascend.com/developer/download/community

# 安装（根据实际CANN版本替换文件名）
chmod +x Ascend-cann-toolkit_linux-aarch64.run
./Ascend-cann-toolkit_linux-aarch64.run --install --install-for-all --quiet

Install CANN kernels (recommended)

chmod +x Ascend-cann-kernels_linux-aarch64.run
./Ascend-cann-kernels_linux-aarch64.run --install --install-for-all --quiet

Configure environment variables

source /usr/local/Ascend/ascend-toolkit/set_env.sh
echo "source /usr/local/Ascend/ascend-toolkit/set_env.sh" >> ~/.bashrc
source ~/.bashrc

Verify the CANN installation

cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg

3.3 Python Environment Configuration

Create a virtual environment

For bare-metal environments, it is recommended to use conda to manage the Python environment; for container environments, simply use pip directly, and conda or venv is not required.

# 裸机环境：使用conda创建环境（推荐）
conda create -n npu_env python=3.10 -y
conda activate npu_env

# 容器环境：直接使用pip，无需conda或venv

Install PyTorch

You MUST preferentially obtain the wget download link for the corresponding version from the official installation guide: https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md

Based on the target PyTorch version, architecture (aarch64/x86_64), and Python version, find the corresponding download link in the above document.

# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：PyTorch 2.6.0 + aarch64 + Python 3.10
wget https://download.pytorch.org/whl/cpu/torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch-2.6.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

# 示例：PyTorch 2.6.0 + x86_64 + Python 3.10
# wget https://download.pytorch.org/whl/cpu/torch-2.6.0%2Bcpu-cp310-cp310-linux_x86_64.whl
# pip install torch-2.6.0+cpu-cp310-cp310-linux_x86_64.whl

# 方式2：pip直接安装（备选，网络通畅时使用）
# aarch64架构（ARM/鲲鹏）
# pip install torch==2.6.0

# x86_64架构
# pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu

Install torch_npu

You MUST preferentially obtain the wget download link for the corresponding version from the official installation guide: https://www.hiascend.com/document/detail/zh/Pytorch/2600/configandinstg/instg/docs/zh/installation_guide/installation_via_binary_package.md

The torch_npu version must strictly correspond to the PyTorch version and the CANN version. Find the corresponding download link in the above document.

pip install pyyaml setuptools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# 方式1：wget下载whl包安装（推荐，优先使用）
# 示例：torch_npu 2.6.0.post5 + aarch64 + Python 3.10
wget https://gitcode.com/Ascend/pytorch/releases/download/v7.3.0-pytorch2.6.0/torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
pip install torch_npu-2.6.0.post5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

# 方式2：pip直接安装（备选，网络通畅时使用）
# pip install torch-npu==2.6.0.post5

Verify the torch_npu installation

import torch
import torch_npu

print(f"PyTorch version: {torch.__version__}")
print(f"torch_npu version: {torch_npu.__version__}")
print(f"NPU available: {torch.npu.is_available()}")
if torch.npu.is_available():
    print(f"NPU device count: {torch.npu.device_count()}")
    print(f"NPU device name: {torch.npu.get_device_name(0)}")
    x = torch.randn(3, 3).npu()
    y = torch.randn(3, 3).npu()
    z = x + y
    print(f"NPU compute test passed: {z.shape}")

IV. Environment Variable Configuration

4.1 Required Environment Variables

# CANN环境（MUST）
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# torch_npu日志级别（可选，调试时设置）
export ASCEND_LOG_LEVEL=3  # 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR

# NPU可见设备（可选）
export ASCEND_RT_VISIBLE_DEVICES="0"  # 只使用NPU:0

4.2 Performance Optimization Environment Variables

# 算子编译优化
export ASCEND_AICPU_PATH=/usr/local/Ascend/ascend-toolkit
export TASK_QUEUE_ENABLE=1

# 内存优化
export PYTORCH_NPU_ALLOC_CONF=max_split_size_mb:32

# HCCL通信超时（分布式训练时建议设置）
export HCCL_CONNECT_TIMEOUT=1800

V. Installation of Common Third-Party Libraries

Ascend NPU servers are usually based on the ARM (aarch64) architecture, and the precompiled wheel packages of some third-party libraries may be incompatible. It is recommended to install them by compiling from source first.

5.0 Third-Party Libraries Supported by Ascend (Use First)

Before installing third-party libraries, you MUST check the latest version of the third-party library support list on the Ascend official website in real time, preferentially use versions that Ascend has adapted, and install strictly according to their version requirements. Ascend has adapted some mainstream third-party libraries for NPU; using the adapted libraries can provide better performance and compatibility.

Lookup path: Ascend Official Website → Documentation → PyTorch Framework Adaptation → Third-Party Library Adaptation → Supported Suites and Third-Party Libraries

Reference link (versions iterate quickly; you MUST refer to the latest version of the official website documentation):https://www.hiascend.com/document/detail/zh/Pytorch/2600/modthirdparty/modparts/FrameworkPTAdapter/26.0.0/zh/supported_suites_and_third_party_libraries/supported_suites_and_third_party_libraries.md

Known third-party libraries natively supported by Ascend include (subject to the official documentation):

transformers：pip install transformers, natively supports Ascend NPU

accelerate：pip install accelerate, natively supports Ascend NPU

peft：pip install peft, natively supports Ascend NPU

trl：pip install trl, natively supports Ascend NPU

deepspeed: Requires the Ascend-adapted version; see the official documentation

Installation principles:

First check the above official documentation to confirm whether an Ascend-adapted version of the target library is available

If an adapted version is available, operate strictly according to the version requirements and installation instructions in the official documentation

If there is no suitable version, then use compilation and installation or pip installation

5.1 FFmpeg (video processing)

# 编译安装（ARM架构下pip可能无预编译包）

# 1. 下载FFmpeg源码
wget https://ffmpeg.org/releases/ffmpeg-8.1.tar.gz
tar -zxvf ffmpeg-8.1.tar.gz

# 2. 编译
cd ffmpeg-8.1
./configure --enable-shared
make -j$(nproc)
sudo make install

# 3. 验证
ffmpeg -version

5.2 OpenCV (image processing)

git clone https://github.com/opencv/opencv.git -b 4.8.0 --depth 1
cd opencv && mkdir build && cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D BUILD_opencv_python3=ON \
      -D PYTHON3_EXECUTABLE=$(which python3) \
      ..
make -j$(nproc)
sudo make install

5.3 Other common libraries

Library name	aarch64 installation recommendation
numpy	`pip install numpy` Usually can be installed directly
scipy	`pip install scipy` Usually can be installed directly; if it fails, compile and install
pillow	`pip install pillow` Usually can be installed directly
scikit-learn	`pip install scikit-learn` Usually can be installed directly; if it fails, compile and install
onnx	`pip install onnx` Usually can be installed directly
onnxruntime	Need to check whether an aarch64 precompiled package exists; if not, compile from source
tokenizers	`pip install tokenizers` Usually can be installed directly
transformers	`pip install transformers` Usually can be installed directly

5.4 General template for compilation and installation

git clone <repo_url> -b <version_tag> --depth 1
cd <repo_name>
pip install -e .
# 或
python setup.py build_ext --inplace
pip install .

5.5 Obtaining mirror sites and model resources

NPU servers are usually located in intranet environments, and some websites such as HuggingFace and GitHub may be inaccessible or slow. MUST preferentially use mirror sites or domestic alternative platforms to obtain resources.

Obtaining models and datasets

MUST preferentially use the following methods to obtain models/datasets, NEVER use the HuggingFace official website by default(use only when the user explicitly confirms that the network can reach HuggingFace):

Priority	Method	Description
1	ModelScope（https://www.modelscope.cn）	Domestic platform, stable network, a large number of models equivalent to HuggingFace
2	HuggingFace mirror site (https://hf-mirror.com）	Set `export HF_ENDPOINT=https://hf-mirror.com` then use huggingface_hub normally
3	HuggingFace official website (https://huggingface.co）	Use only when the user explicitly confirms that the network can reach it

ModelScope usage example：

# 安装modelscope
pip install modelscope -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# 从ModelScope下载模型（替代HuggingFace的from_pretrained）
from modelscope import snapshot_download
model_dir = snapshot_download('模型ID')

# 使用transformers加载ModelScope下载的模型
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(model_dir)

How to use the HuggingFace mirror site：

# 设置环境变量后，huggingface_hub会自动使用镜像站
export HF_ENDPOINT=https://hf-mirror.com

# 或在Python代码中设置
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

Obtaining code repositories

Original site	Mirror site	Usage example
GitHub	https://bgithub.xyz	Replace `github.com` with `bgithub.xyz`, such as `git clone https://bgithub.xyz/user/repo.git`
GitHub	https://gitcode.com	Some repositories have mirrors on gitcode

6. Project dependency installation

6.1 Installation strategy

When installing dependencies according to the requirements.txt in the code repository, follow these principles:

Minimize impact on existing libraries: Install in an independent virtual environment to avoid polluting the system environment
When version requirements are strict: First try installing with relaxed version requirements and record the changes
When actual operation is abnormal: Roll back to the strict versions and record the reasons for conflicts

6.2 Installation steps

# 1. 先尝试使用阿里源安装requirements.txt
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# 如阿里源失败，尝试清华源
# pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 如镜像源均失败，回退至pip默认源
# pip install -r requirements.txt

# 2. 如遇版本冲突，逐个安装并记录
# 记录格式：包名 | 原要求版本 | 实际安装版本 | 是否有变更 | 变更原因
pip install package_name==specific_version -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

# 3. 如严格版本与torch_npu环境冲突，尝试放宽版本
# 示例：原要求 numpy==1.24.0，假设不兼容
# 放宽为 numpy>=1.24.0
pip install "numpy>=1.24.0" -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com
# 记录：numpy | ==1.24.0 | >=1.24.0 | 是 | 与某某版本冲突

6.3 Dependency conflict handling

Conflict 1: The project requires the CUDA version of PyTorch, but the NPU requires the CPU version or the aarch64 version → For the aarch64 architecture, install the official PyTorch package directly; for x86_64, install the CPU version of PyTorch + torch_npu
Conflict 2: Some packages depend on the nvidia-* library → Check whether it is a hard dependency; if it is only an optional acceleration, it can be ignored
Conflict 3: The numpy/scipy versions are incompatible with torch_npu → Refer to the recommended versions in the official torch_npu documentation and relax the version constraints in requirements
Conflict 4: requirements specifies CUDA suffixes such as torch==x.y.z+cu118 → Replace with torch==x.y.z(without the CUDA suffix); after installation, NPU support is provided by torch_npu

7. Environment verification checklist

VIII. Common Pitfalls

Pitfall 1: During manual installation, installing the CUDA version of PyTorch and then installing torch_npu causes a conflict → On the aarch64 architecture, install the official PyTorch package; on the x86_64 architecture, you MUST install the CPU version of PyTorch
Pitfall 2: The CANN version does not match the torch_npu version, causing errors at runtime → Match them strictly according to the version compatibility matrix, based on the compatibility table published on the Ascend official website
Pitfall 3: Forgetting source set_env.sh, causing the CANN library to not be found → Add the source command to ~/.bashrc or the virtual environment activation script
Pitfall 4: The Docker container exits immediately after starting → Use the -dit parameter to start in interactive + background mode, first docker start and then docker exec -it to enter
Pitfall 5: The Docker container lacks NPU device mapping, andtorch.npu.is_available() returns False → When starting the container, you MUST add parameters such as --device=/dev/davinci_manager and mount the driver libraries
Pitfall 6: Installing third-party libraries directly with pip on the ARM architecture fails → Prefer installation by compiling; see Chapter 5
Pitfall 7: During manual installation, installing kernels before toolkit causes the installation to fail → You MUST install toolkit before kernels
Pitfall 8: The NPU driver is unavailable after an automatic kernel upgrade → Ubuntu:apt-mark hold linux-image-generic linux-headers-generic linux-image-extra → openEuler：yum install yum-plugin-versionlock && yum versionlock add kernel-$(uname -r) → Source: Atlas 800T A2 Installation Guide EDOC1100349380, Atlas 800I A3 Installation Guide EDOC1100471070
Pitfall 9: Wrong Docker image tag selected (chip model mismatch) → For the correspondence between chip models and product series, please refer to the Ascend official documentation