> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r3al.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the thin client and connect it to the R3AL platform.

## Requirements

* Python **3.10+**
* Windows, Linux, or macOS
* An R3AL platform account and API key (quantization runs on the platform)

## Prerequisite: account + API key

Quantization runs on the R3AL platform, so you need a key before you can submit a job:

<Steps>
  <Step title="Create an account">
    Sign up at [platform.r3al.ai](https://platform.r3al.ai) and verify your email.
  </Step>

  <Step title="Create an API key">
    On the **SDK / API keys** page, mint a key (`r3l_live_...`). Copy it immediately: the secret is shown only once.
  </Step>
</Steps>

See [Using the platform](/guides/platform) for the full walkthrough.

## Install from PyPI

```bash theme={null}
pip install "r3alai[vision]"
```

The base package is a thin client (`pydantic` + `numpy`, **no torch**). The `vision` extra adds what you need to run and benchmark the downloaded quantized model locally.

## Install from source

```bash theme={null}
git clone https://github.com/R3AL-AI/SDK.git
cd SDK
pip install -e ".[vision]"
```

## Extras

| Extra           | Installs                                                             | Needed for                                                                      |
| --------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `vision`        | onnx, onnxruntime-gpu (Linux/Windows) or onnxruntime (macOS), pillow | Running and benchmarking the downloaded model locally (`benchmark()`, `load()`) |
| `export-torch`  | torch, onnx, onnxscript                                              | Exporting a PyTorch checkpoint or `nn.Module` to ONNX locally before upload     |
| `yolo`          | ultralytics, opencv, PyYAML, ...                                     | Ultralytics (YOLO) export and mAP validation                                    |
| `export-tf`     | tensorflow, tf2onnx                                                  | TensorFlow / Keras export                                                       |
| `export-paddle` | paddlepaddle, paddle2onnx                                            | Paddle export                                                                   |
| `export-tflite` | tflite2onnx                                                          | TFLite export                                                                   |
| `export-hf`     | optimum-onnx, transformers                                           | Exporting a HuggingFace Hub model to ONNX with [`r3al export`](/cli/commands)   |
| `dev`           | ruff                                                                 | Contributing                                                                    |
| `all`           | vision + yolo + all export extras                                    | Everything                                                                      |

<Note>
  The base install has **no torch** and no ONNX Runtime. Add `vision` to run the deliverable locally, and an `export-*` extra only if you need the SDK to convert framework weights to ONNX before upload. If you already have an `.onnx` file, `vision` alone is enough.
</Note>

<CodeGroup>
  ```bash Run + benchmark locally theme={null}
  pip install "r3alai[vision]"
  ```

  ```bash + local PyTorch export theme={null}
  pip install "r3alai[vision,export-torch]"
  ```

  ```bash + Ultralytics (YOLO) theme={null}
  pip install "r3alai[vision,yolo]"
  ```

  ```bash Everything theme={null}
  pip install "r3alai[all]"
  ```
</CodeGroup>

## The `r3al` command

Installing the package also puts an `r3al` command on your PATH, covering the
same workflow from a terminal or a coding agent:

```bash theme={null}
r3al login
r3al inspect model.onnx
```

See the [CLI documentation](/cli/overview). Only `quantize` and `qat` consume a
plan run, and both refuse to submit without `--yes`.

## Verify

```bash theme={null}
python -c "from r3alai.quant import Quantizer, QuantConfig; import r3alai.platform; print('OK')"
```

Then authenticate and confirm the platform sees your key:

```python theme={null}
import r3alai.platform as platform

platform.login("r3l_live_...")
print(platform.PlatformClient().usage())   # plan + remaining free runs
```

## GPU support

Quantization always runs on R3AL GPU infrastructure, so you do not need a local GPU to quantize. Locally, the `vision` extra installs `onnxruntime-gpu` on Linux and Windows and the CPU build on macOS (`onnxruntime-gpu` has no macOS wheels). Local `benchmark()` and `load()` transparently fall back to CPU when no GPU is present.

For CUDA inference with ONNX Runtime on Windows, ensure the NVIDIA runtime DLLs (installed under `site-packages/nvidia/*/bin` by the pip CUDA packages) are on `PATH`.