Installation and Environment Check

Installation and Environment Check#

This chapter covers the environment needed to run qb Compiler, how to install the Python package, how to choose a target device string, and how to confirm that the compiler can see its commands and default configuration.

System Requirements#

Use a Linux environment for compilation. Mobilint recommends the official Docker images because they keep Python, CUDA, framework, and compiler dependencies aligned.

Recommended baseline:

  • Ubuntu 20.04 or later

  • Docker

  • NVIDIA Container Toolkit when using the CUDA image

  • NVIDIA GPU for faster compilation, especially for large vision models and LLMs

A CPU-only Docker image is also supported for environments without NVIDIA GPUs. Compilation may take longer.

Install qbcompiler#

Use a Docker image whose major and minor tag matches the qbcompiler wheel version. For example, use a 1.0-* Docker image with a qbcompiler-1.0.* wheel.

CUDA image example:

docker pull mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04
docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04 /bin/bash

If models and datasets live outside the working directory, mount them explicitly:

docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  -v {PATH_TO_MODEL_DIR}:/models \
  -v {PATH_TO_DATASET_DIR}:/datasets \
  mobilint/qbcompiler:1.0-cuda12.8.1-ubuntu22.04 /bin/bash

CPU-only image example:

docker pull mobilint/qbcompiler:1.0-cpu-ubuntu22.04
docker run -it --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.0-cpu-ubuntu22.04 /bin/bash

Install the qbcompiler wheel inside the container:

python -m pip install /path/to/qbcompiler-{VERSION}-py3-none-any.whl

Starting with qbcompiler 1.2, wheel filenames do not include an NPU name. For example, the 1.2.0 wheel is named qbcompiler-1.2.0-py3-none-any.whl. Wheels before 1.2 may include an NPU name in the local version segment, such as qbcompiler-1.1.2+aries2-py3-none-any.whl; install the exact wheel file provided for that release.

Select the Target Device#

Every MXQ is compiled for a target device. Use the exact target device string in CLI options and Python calls:

Target device string

NPU Chip

aries-rb

ARIES

regulus-ra

REGULUS

regulus-rb

REGULUS

Example CLI option:

python -m qbcompiler compile --target-device regulus-rb ...

Example Python argument:

target_device = "regulus-rb"

If you compile for one target device and deploy to a different target device, the MXQ may fail to load or may not run correctly.

Verify the Installation#

After installation, confirm that Python can import the package:

python - <<'PY'
import qbcompiler
print(qbcompiler.__version__)
PY

Then confirm that the CLI is available:

python -m qbcompiler --help
python -m qbcompiler compile --help

The core CLI commands are:

  • compile: original model to MXQ in one command

  • parse: original model to MBLT

  • quantize: MBLT to MXQ

  • dump-config: write a default or preset-based config file

Check Presets and the Default Config#

List built-in presets:

python -m qbcompiler presets

Common presets include:

  • classification

  • detection

  • classification_torchvision

  • yolo_640

  • yolo_1280

  • llm

  • llm_fast

  • vision_transformer

  • multimodal

Dump a config before editing it:

python -m qbcompiler dump-config --preset classification_torchvision --output compile_config.yaml

Use this file as the starting point for repeatable builds. A config file is also the safest way to keep CLI and Python workflows aligned across teams.