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.3-cuda12.8.1-ubuntu22.04
docker run -it --gpus all --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.3-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.3-cuda12.8.1-ubuntu22.04 /bin/bash

CPU-only image example:

docker pull mobilint/qbcompiler:1.3-cpu-ubuntu22.04
docker run -it --ipc=host \
  --name {YOUR_CONTAINER_NAME} \
  -v $(pwd):/workspace \
  mobilint/qbcompiler:1.3-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.3.0 wheel is named qbcompiler-1.3.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

regulus-rb-usb

REGULUS

regulus-rb-usb is available from qbcompiler 1.3. It targets a USB-attached REGULUS device, whose NPU I/O boundary is not floating point, so an MXQ built for regulus-rb is not interchangeable with one built for regulus-rb-usb.

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. This form works on every release:

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

From qbcompiler 1.3 the installation also puts a qbcompiler command on PATH, which runs the same entry point through the same output protocol:

qbcompiler --help

On 1.2 that command does not exist, so a command not found there means the release predates it, not that the installation failed. The rest of this manual uses the python -m qbcompiler form for that reason, except the release notes, which show the new command as the feature it is. Substitute qbcompiler freely on 1.3.

The form is not the only difference on 1.2. The compile and quantize subcommands did not run at all on 1.2.0 — they reached the compile entry point without a target device and failed internally — so the command examples in this manual need 1.3 regardless of which spelling you use. parse, presets, dump-config and check are unaffected.

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

  • info: print an MBLT’s provenance record as JSON (qbcompiler 1.3 and later)

Check Presets and the Default Config#

List built-in presets:

QBCOMPILER_JSONL=1 python -m qbcompiler presets

presets and check report on the JSONL channel, so they print nothing unless it is on. Set QBCOMPILER_JSONL=1 to see their output; an empty result is not a failed install.

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.