Ascend CANN Installation Guide for Container Environment

This guide is based on the Ascend CANN official image and helps you quickly set up an Ascend AI operator development environment through Docker containerization.

Note

Disclaimer This document and related scripts are for learning and reference only. They do not guarantee stability or security in production environments. Users must evaluate the risks and assume corresponding responsibilities.

Prerequisites

Before you begin, ensure that the following environment is ready:

Condition	Description	Verification Command
Docker engine	Installed and the daemon is running	`docker info`
Network connectivity	Accessible to the Huawei Cloud image repository for pulling images and downloading scripts	`ping swr.cn-south-1.myhuaweicloud.com`

After meeting the above prerequisites, completing the environment setup and starting the container as described in this document typically takes less than 5 minutes (depending on network speed). If a CANN image is locally available, it can be completed in seconds.

1. Preparing the Image

1.1 Querying Local Images

Run the following command to query existing CANN images in the current environment:

docker images | grep cann

If the returned result contains a CANN image, an example output is as follows:

REPOSITORY                                          TAG                                               IMAGE ID            CREATED             SIZE
swr.cn-south-1.myhuaweicloud.com/ascendhub/cann     8.5.1-910b-openeuler24.03-py3.11                  6df0c5bbc16f        2 weeks ago         17.1GB

If a suitable version already exists, you can directly skip to Section 2: Starting the Container.

1.2 Pulling a CANN Image

If no local image is available, follow the steps below.

Step 1 Visit the CANN Image Repository, switch to the "Image Versions" tab, and browse the list of available versions:

Step 2 Select an image version based on the following suggestions:

Option	Suggestion
CANN Version	If no special requirements exist, it is recommended to select the latest stable version.
Chip Model	Select based on the actual hardware (run `npu-smi info` to check).
Operating System	Either openEuler or Ubuntu is acceptable; openEuler is recommended.

Step 3 Copy the full image version number (for example: 8.5.1-910b-openeuler24.03-py3.11) and assemble the pull command in the following format:

docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:<image version>

Execution example (takes approximately 3–5 minutes, depending on network conditions):

docker pull swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.1-910b-openeuler24.03-py3.11

Note

Why is the image name (swr.cn-south-1.myhuaweicloud.com/ascendhub/cann) so long?
Because the full path format includes the complete registry address, allowing direct pulling without additional Docker registry configuration, enabling out-of-the-box use.

2. Starting the Container

2.1 Downloading the Container Startup Script

Run the following command to download:

cd ~
curl -fLO --retry 10 --retry-all-errors --retry-delay 3 -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" https://raw.gitcode.com/Ascend/msot/raw/master/example/quick_start/public/ctr_in.py && chmod +x ctr_in.py

Note

If the prompt says the --retry-all-errors parameter does not exist, it means the curl version is too low. You can remove this parameter and try again;
If the download still fails after multiple attempts, it may be because a CDN protection mechanism against automated script crawling has been triggered. You can manually download the ctr_in.py file from the repository;

2.2 Running the Start Command

Parameters:

Parameter	Description	Example
`CONTAINER_NAME`	Container name, which can be used to log in to the container later. Recommended format: `{Purpose}_{ID}`	`op_dev_alice`
`USER_NAME`	Username on the host machine, used to mount the `$HOME` directory for data sharing.	`alice`
`IMAGE`	Docker image ID or full name.	`6df0c5bbc16f`

Command Format:

python3 ~/ctr_in.py <CONTAINER_NAME> <USER_NAME> <IMAGE>

Example:

# Use the image ID.
python3 ~/ctr_in.py op_dev_alice alice 6df0c5bbc16f

# Use the image full name.
python3 ~/ctr_in.py op_dev_alice alice swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.1-910b-openeuler24.03-py3.11

Expected Output:
After a successful start, you will directly enter the container. The terminal will display the command prompt inside the container, waiting for command input:

Welcome to 5.10.0-60.139.0.166.oe2203.aarch64

System information as of time:  Fri Mar 20 06:46:56 UTC 2026
System load:    8.95
Memory used:    6.2%
Swap used:      55.4%
Usage On:       25%
Users online:   0

[root@localhost alice]#

Note

How to re-enter the container after exiting?

Execute: python3 ~/ctr_in.py op_dev_alice. When only one parameter is passed, the script will perform the operation of entering an existing container and supports fuzzy matching of container names.
You can also use the native Docker command: docker exec -it op_dev_alice bash.