Dev Container

中文版 | English

Ubuntu 24.04 containerized development environment for AscendC NPU kernel development.

📋 Prerequisites

Check Docker and buildx

Confirm Docker is installed with version ≥ 23.0.0:

docker --version

If the command is missing or the version is too low, follow the Docker official installation guide to install or upgrade.

sudo usermod -aG docker $USER && newgrp docker

Image building depends on the docker buildx plugin. Run docker buildx version to check; if the command is not found, install it:

mkdir -p /usr/local/lib/docker/cli-plugins
version="v0.34.1"
arch=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/docker/buildx/releases/download/${version}/buildx-${version}.linux-${arch}" \
     -o /usr/local/lib/docker/cli-plugins/docker-buildx
chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx

🧑‍💻 Quick Start (Human Users)

Step 1: Install VS Code

Download and install the version for your platform from the Visual Studio Code website.

Step 2: Install the Dev Containers extension

In VS Code, press Ctrl+Shift+X to open the Extensions view, then search for and install the Dev Containers extension.

Step 3: Clone the repository

git clone https://gitcode.com/cann/asc-devkit.git
cd asc-devkit

Step 4: Prepare based on NPU availability

4.1 With NPU: verify driver and device nodes

On the host, run:

npu-smi info                        # check NPU status
ls /dev/davinci*                    # confirm device nodes
ls /usr/local/Ascend/driver         # confirm driver directory

If any command fails or returns no output, the Ascend driver is not ready. Refer to the CANN Software Installation Guide - Install on Physical Machine.

If the host has fewer than 8 NPUs, edit .devcontainer/devcontainer.json and remove the extra --device=/dev/davinciN lines (run ls /dev/davinci* to check the actual device count).

4.2 Without NPU: adjust devcontainer.json

Machines without NPU must first remove device and driver mount configurations.

In runArgs, remove all NPU-related entries: the device access flags (--ipc=host, --net=host, --privileged) and --device lines (davinci0-7, davinci_manager, devmm_svm, hisi_hdc), and set it to:

"runArgs": []

In mounts, remove the driver and device-related bind mounts:

source=/usr/local/Ascend/driver,...
source=/usr/local/dcmi,...
source=/usr/local/bin/npu-smi,...
source=/etc/ascend_install.info,...

Keep the ccache volume and any data directories you added yourself.

Step 5: Open the project in the container

Open this project directory in VS Code, press Ctrl+Shift+P, and run:

Dev Containers: Reopen in Container

The Dev Containers extension will automatically build the image and start the container. The first build takes about 5 minutes (mostly downloading the conda environment and PyTorch); subsequent opens hit the Docker layer cache and complete in seconds.

Step 6: Install CANN inside the container

After the container starts, in the container terminal refer to the 📥 Download and Install CANN Packages section to download and install the toolkit and ops packages.

Step 7: Verify environment

In the container terminal, refer to the ✅ Environment Verification section to confirm NPU device and CANN package status, then follow ⚙️ Environment Variable Configuration to load the environment variables. You can then begin kernel development.

🤖 Quick Start (AI Agent)

AI Agents (such as Claude Code, CI runners) can run the container directly without VS Code.

Before running the container, confirm the following with the user:

1. Repository path — where is the project checked out on the host? (default: current directory $PWD).
2. Data directories — are there other data directories to mount (e.g. datasets, model weights)?
3. NPU availability — does the host have Ascend NPUs? (determines which variant to use below).

After confirmation, show the user the exact docker run command you are about to execute and wait for user confirmation before proceeding.

For Docker and buildx checks and installation, see Check Docker and buildx.

Build the image

docker buildx build --network host -t ascendc:ubuntu24.04 .devcontainer/

With NPU

docker run -itd --name ascendc_container \
  --ipc=host --net=host --privileged \
  --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:ro \
  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro \
  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
  -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
  ascendc:ubuntu24.04

If the host has fewer than 8 NPUs, remove the corresponding --device=/dev/davinciN lines (run ls /dev/davinci* to check the actual device count).

Without NPU

docker run -itd --name ascendc_container ascendc:ubuntu24.04

🐍 Python Environment

The container comes with the following conda environment pre-installed:

Default active environment is py312.

⚙️ Configuration

Mirror Sources

Build args and defaults:

Override example:

docker buildx build --network host \
  --build-arg CONDA_MIRROR=https://mirrors.ustc.edu.cn/anaconda \
  --build-arg REPO_SCRIPT_URL=https://storage.googleapis.com/git-repo-downloads/repo \
  -t ascendc:ubuntu24.04 .devcontainer/

Build Cache

The Dockerfile uses BuildKit --mount=type=cache for apt / pip. On re-builds (when non-package layers change), package indexes and previously downloaded wheels are reused and the build finishes in seconds. docker buildx build enables BuildKit by default — no extra configuration required.

Mount Directories

Mount directories vary by developer; add your own in devcontainer.json:

// mounts
"source=/your/data,target=/your/data,type=bind"

NPU Device Selection

Device nodes are passed explicitly with --device=/dev/davinciN. If the host has fewer than 8 NPUs, remove the corresponding lines. For example, for a 4-NPU host:

--device=/dev/davinci0 \
--device=/dev/davinci1 \
--device=/dev/davinci2 \
--device=/dev/davinci3 \