Installation¶

Install torch-rbln from pre-built wheels or build it from source. To compile and run models on RBLN NPUs, you must install rebel-compiler separately from the RBLN package index.

Use import torch in Python as usual and torch-rbln is available. torch-rbln autoloads as an out-of-tree extension, so no extra import is needed.

1
2
3

import torch

x = torch.ones(4, dtype=torch.float16, device="rbln")

For version history, see the release notes.

Version pairing¶

torch-rbln is built against a specific rebel-compiler interface and a specific PyTorch CPU wheel. Install all three from the same SDK release.

import torch checks ABI (Application Binary Interface) compatibility between torch-rbln and rebel-compiler. A pair from different releases fails at import with an RBLN ABI mismatch message. See Troubleshoot.

Quickstart¶

Create a virtual environment, install the packages, then verify.

1
2
3

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

Install torch-rbln from PyPI together with the torch CPU wheel it pins:

1
2
3
4
5

$ pip install \
  --index-url https://download.pytorch.org/whl/cpu \
  torch==2.13.0+cpu
$ pip install \
  torch-rbln==0.12.0

Install rebel-compiler from the RBLN package index (RBLN Portal credentials required):

1
2
3

$ pip install \
  --extra-index-url https://pypi.rbln.ai/simple \
  rebel-compiler==0.12.0

Verification¶

Run the environment report first. It does not need an NPU and it does not execute any operator:

1

python -m torch_rbln.diagnose

When the environment is set up correctly, the output looks like the following. Values differ per machine; check that loaded from: under torch-rbln package: and rebel-compiler package: point into the environment you activated, and that rebel ABI handshake: ends with verdict: OK:

...
=== torch-rbln environment diagnostics ===

torch-rbln package:
  version: <TORCH_RBLN_VERSION>
  install_type: normal
  loaded from: /path/to/.venv/lib/python3.x/site-packages/torch_rbln
  installed at: /path/to/.venv/lib/python3.x/site-packages/torch_rbln
  lib_dir: /path/to/.venv/lib/python3.x/site-packages/torch_rbln/lib (exists: True)
  native .so in lib: libc10_rbln.so, ...

rebel-compiler package:
  version: <REBEL_COMPILER_VERSION>
  install_type: normal
  loaded from: /path/to/.venv/lib/python3.x/site-packages/rebel
  installed at: /path/to/.venv/lib/python3.x/site-packages/rebel

rebel ABI handshake:
  built against ABI: <N>
  librbln.so: /path/to/.venv/lib/python3.x/site-packages/tvm/librbln.so
  runtime accepts: <MIN>..<CURRENT> (min_supported..current)
  verdict: OK

Environment variables (affecting library search):
  LD_LIBRARY_PATH= (not set)
  PYTHONPATH= (not set)
...

The report is written to stderr; read its text. The module does not load the torch native libraries or the RBLN extension, so it prints even when import torch itself fails.

Then run one operation on the device with fallback logging on. If the log contains no op ran on CPU line, no fallback was detected and the operation ran on the device. The command reads the result back with .cpu() before printing, because printing an rbln tensor directly runs host-side formatting operators that would themselves appear in the fallback log:

1

TORCH_RBLN_LOG_LEVEL=INFO python -c "import torch; a = torch.ones(64, dtype=torch.float16, device='rbln'); c = a + a; print(c.device, c.cpu()[:3])"

rbln:0 tensor([2., 2., 2.], dtype=torch.float16)

The first call compiles the operator and takes noticeably longer than a later call in the same process; that is expected, and every new process compiles again. If the output shows the tensor and no op ran on CPU line, you are done. If it fails:

• RuntimeError: Cannot find libraries: ['librbln.so', 'librbln_runtime.so'] or FileNotFoundError: Could not find librbln.so: rebel-compiler is not installed in this environment, or another stack's LD_LIBRARY_PATH shadows it. See Troubleshoot.
• RBLN ABI mismatch: ...: torch-rbln and rebel-compiler come from different releases. Reinstall both from one release. See Troubleshoot.
• torch.rbln.device_count() returns 0: no NPU is visible to this process. Check rbln-smi, the RBLN_VISIBLE_DEVICES setting, and container device passthrough. See Troubleshoot.

Optionally print the device topology to confirm which physical NPUs back each logical device:

1

python -c "import torch; torch.rbln.device_summary()"

[RBLN] Device Topology Initialized:
+----------------+------------------+---------------------+
| Logical Device | Physical NPU IDs | Status              |
+----------------+------------------+---------------------+
| rbln:0         | [ 0 ]            | Active              |
+----------------+------------------+---------------------+

Docker¶

The Installation Guide install matrix lists the SDK container images and the docker pull command for each supported OS and Python version. The images carry rebel-compiler; add torch-rbln inside the container with the pip command above. Pass the NPU device nodes into the container with the RBLN Container Toolkit.

Upgrade¶

The Quickstart commands pin exact versions, so running the new release's commands replaces all three packages together. After upgrading, re-run Verification.

Uninstall¶

1

pip uninstall -y torch-rbln

rebel-compiler and torch are independent packages; remove them only if nothing else in the environment needs them.

Build from source (advanced)¶

Repository: torch-rbln

machine pypi.rbln.ai
login <your-rbln-portal-id>
password <your-rbln-portal-password>

1
2
3
4

git clone https://github.com/RBLN-SW/torch-rbln.git
cd torch-rbln
uv venv .venv && source .venv/bin/activate
uv pip install -U pip

1

./tools/dev-setup.sh pypi

❌ Cannot reach any rbln pypi index (no permission or network error).

1
2

uv sync --no-install-project
uv pip install -e . --no-build-isolation

Next steps¶

• Tutorial: Running and debugging - A first operation, a module, fallback logs, explain().
• Execution Semantics - What to expect from device="rbln" before porting a model.
• Environment Variables - Device mapping for multi-NPU hosts and logging.