Windows Setup — Getting Started with WSL2

The Voyager SDK is built for Linux. On Windows, you run it inside Windows Subsystem for Linux (WSL2) — a real Linux environment that runs alongside Windows.

WSL2 setup path​

Step 1: Install WSL2​

Open PowerShell as Administrator and run:

wsl --install -d Ubuntu-22.04

Restart your computer when prompted. After restart, Ubuntu will open and ask you to create a username and password.

Step 2: Install the Windows driver​

The Axelera Windows driver is not yet Microsoft-certified (certification is in progress). Until then, it requires testsigning mode to install.

2a. Enable testsigning​

Open a Command Prompt as Administrator and run:

bcdedit /set testsigning on

Restart your PC. The desktop will show "Test Mode" in the lower-right corner — this confirms testsigning is active.

2b. Download the drivers​

Download the driver archives from the Axelera software portal:

• Metis driver (required for all hardware): MetisDriver-1.3.4.zip
• Switchtec PCIe switch driver (required only for the Metis PCIe 4-AIPU card): switchtec-kmdf-0.7_2019.zip

Extract each archive locally. Each extracted folder contains three files: .cat, .inf, and .sys.

2c. Remove any previous driver version​

If you already have an older Metis driver installed, remove it completely before installing the new one. Windows can keep multiple drivers for the same device.

In Device Manager, locate the Metis device under Neural Processors, right-click and select Uninstall device:

In the confirmation dialog, check "Attempt to remove the driver for this device", then click Uninstall:

Verify the device now appears under Other devices as a generic PCI Device — this confirms the driver is fully removed:

2d. Install via Device Manager​

Open Device Manager (right-click the Windows Start button → Device Manager).

From the menu, open Action → Add Drivers:

Set the path to the folder where you extracted the Metis driver files:

Select Install the driver anyway when prompted:

Confirm that the Metis device now appears under Neural Processors:

If you have a Metis PCIe 4-AIPU card, repeat the same steps for the Switchtec driver:

Step 3: Enter WSL2 and follow the Linux guide​

Open a regular Command Prompt (not PowerShell, not Administrator) and enter WSL:

wsl

You're now in Linux. From here, follow the standard setup:

1. Hardware Install — verify your Metis device is detected
2. SDK Install — clone, install, and activate
3. Verify Setup — confirm everything works

Step 4: Where to clone the SDK​

Clone the SDK in a Windows-accessible folder so both Windows and WSL can reach it:

# Inside WSL — /mnt/c/ maps to C:\ on Windows
cd /mnt/c/Axelera
git clone https://github.com/axelera-ai-hub/voyager-sdk.git
cd voyager-sdk

This means:

• From WSL: /mnt/c/Axelera/voyager-sdk
• From Windows: C:\Axelera\voyager-sdk

Native Windows inference​

If you need to run inference natively on Windows without WSL, follow these steps. All commands below run in Windows — not in WSL.

Step 1: Install Python​

1. Download Python for Windows — use the official website, not the Microsoft Store.

2. During installation:

   • Enable "Add Python to PATH"
   • Select "Disable path length limit" when prompted

3. Add the Python installation path and the Python\Scripts path to the Windows Path environment variable:

   

4. Create a virtual environment:

   python -m venv venv-win
   

Step 2: Download Windows packages​

Open a regular Command Prompt (not PowerShell, not Administrator) and navigate to your SDK directory:

cd C:\Axelera\voyager-sdk

Create a local download directory and download all packages:

rmdir /s /q windows-packages 2>nul
mkdir windows-packages
cd windows-packages

curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.6.x/axelera-win-device-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.6.x/axelera-win-runtime-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.6.x/axelera-win-syslibs-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.6.x/axelera-win-toolchain-deps-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-win/packages/1.6.x/axelera-win-services-installer.exe
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-runtime/axelera_runtime-1.6.0-py3-none-any.whl
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-types/axelera_types-1.6.0-py3-none-any.whl
curl -L -O https://software.axelera.ai/artifactory/axelera-runtime-pypi/axelera-llm/axelera_llm-1.6.0-py3-none-any.whl

cd ..

Step 3: Install the executable packages​

Using Windows Explorer, navigate to C:\Axelera\voyager-sdk\windows-packages and run each .exe installer in sequence.

After installation, verify via Settings → Apps & features (or Add or remove programs):

All five packages must be listed:

You must see: Axelera Cross Compiled Libraries Package, Axelera Device Package, Axelera Runtime, Axelera Services, and RISC-V Toolchain and Dependencies for Axelera. Exact version numbers will vary.

Restart your Command Prompt window after all installers complete before proceeding.

Step 4: Install Python packages​

Activate the virtual environment and install the wheels:

venv-win\Scripts\activate.bat

pip install windows-packages\axelera_runtime-1.6.0-py3-none-any.whl
pip install windows-packages\axelera_types-1.6.0-py3-none-any.whl
pip install windows-packages\axelera_llm-1.6.0-py3-none-any.whl

venv-win\Scripts\activate.bat

Step 5: Run examples​

First, obtain a deployed model. If you completed the WSL2 setup and deployed a model there, it is accessible from Windows at C:\Axelera\voyager-sdk\build\. If not, download a pre-built model:

axdownloadmodel resnet50-imagenet-onnx

The model downloads to C:\Axelera\voyager-sdk\build\.

Run inference using the axrunmodel utility (measures performance):

axrunmodel C:\Axelera\voyager-sdk\build\resnet50-imagenet-onnx\resnet50-imagenet-onnx\1\model.json

This runs the model multiple times and prints runtime statistics.

Run inference using the Python API:

Download an image to C:\Axelera\voyager-sdk\examples\axruntime\images, then:

cd examples\axruntime
python -m axruntime_example -v --aipu-cores 1 --labels imagenet-labels.txt ..\..\build\resnet50-imagenet-onnx\resnet50-imagenet-onnx\1\model.json images

Step 6: Run LLM models​

A set of precompiled LLM models can run natively on Windows. To see available models:

axllm --help-network

Run a model in single-prompt mode:

axllm llama-3-2-1b-1024-4core-static --prompt "Give me a joke"

Run interactively in chat mode:

axllm llama-3-2-1b-1024-4core-static

For all options, see the LLM Inference Guide.

Using PowerShell​

After completing installation, you can use PowerShell instead of Command Prompt. The only difference is how you activate the virtual environment:

.\venv-win\Scripts\Activate.ps1

Once activated, all the same commands work as in Command Prompt.

Get-ExecutionPolicy

Set-ExecutionPolicy RemoteSigned

Troubleshooting​

See also​

• SDK Install — the main installation guide (run inside WSL2)
• Verify Setup — confirm hardware and SDK are working
• LLM Inference Guide — full LLM options including Windows
• Glossary: AIPU — the AI Processing Unit on Metis hardware