# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

Example Python argument:

```python
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:

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

Then confirm that the CLI is available:

```bash
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:

```bash
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:

```bash
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.