LynxBenchAI — User Guide

What You’ll Need

Before you begin, make sure you have:

• A computer running Linux (Ubuntu 22.04 or later recommended) or Windows with WSL2 installed.
• Python 3.11 or later installed on your system.
• An internet connection (for installing packages and submitting results).
• Approximately 15 GB of free disk space (for Python packages, AI frameworks, and model data).

Supported Hardware

LynxBenchAI supports benchmarking on the following hardware:

Step 1 — Open a Terminal

On Linux

Open your terminal application. You can usually find it by searching for “Terminal” in your application menu, or by pressing Ctrl + Alt + T.

On Windows (WSL2)

1. Open the Start menu and search for “Ubuntu” (or whichever Linux distribution you installed via WSL2).
2. Click on it to open a Linux terminal window.

Don’t have WSL2? Follow Microsoft’s official guide to install it. In short, open PowerShell as Administrator and run: wsl --install (this installs WSL2 by default on Windows 10 version 2004+ and Windows 11).

Important: WSL version 1 is not supported. GPU passthrough (required for NVIDIA, AMD, and Intel GPU benchmarks) only works with WSL2. To check your version, run wsl -l -v in PowerShell. If your distribution shows “1” under VERSION, convert it with: wsl --set-version Ubuntu 2

Step 2 — Check Your Python Version

LynxBenchAI requires Python 3.11 or later. Check your version by typing this command in the terminal and pressing Enter:

python3 --version

You should see something like:

Python 3.12.4

The number after “Python” must be 3.11 or higher. If your version is older (e.g., 3.10 or 3.9), you will need to update Python before continuing.

sudo apt update
sudo apt install python3.12 python3.12-venv

sudo dnf install python3.12

Step 3 — Create a Virtual Environment

A virtual environment is an isolated space for Python packages, keeping your system clean and avoiding conflicts with other software. LynxBenchAI requires one to be active.

Create the environment

Choose a folder where you’d like to work (for example, your home directory), then run:

python3 -m venv lynxbench-ai-env

This creates a folder called lynxbench-ai-env containing the isolated environment.

Activate the environment

source lynxbench-ai-env/bin/activate

Once activated, you’ll see the environment name in your terminal prompt:

(lynxbench-ai-env) user@machine:~$

Important: You must activate the virtual environment every time you open a new terminal session. If you close the terminal and come back later, run the source lynxbench-ai-env/bin/activate command again.

Step 4 — Install LynxBenchAI

With your virtual environment active (you should see (lynxbench-ai-env) in your prompt), install LynxBenchAI using pip:

pip install lynxbench-ai

This will download and install the LynxBenchAI benchmark tool and all of its dependencies.

Note: The installation may take a few minutes depending on your internet speed. You may see a lot of text scrolling by — this is normal.

Step 5 — Set Up Your Hardware (Drivers)

This step installs the necessary hardware drivers for your device. You only need to do this once per system, or if you change your hardware.

Skip this step if you already have up-to-date GPU drivers installed, or if you are benchmarking on CPU only.

Run the following command, replacing vendor_name with the appropriate name from the Supported Hardware table:

lynxbench-ai setup system vendor_name

Examples:

# For NVIDIA GPUs:
lynxbench-ai setup system nvidia

# For AMD GPUs:
lynxbench-ai setup system amd

# For Intel GPUs:
lynxbench-ai setup system intel

Note: This command may ask for your administrator password (sudo) because driver installation requires system-level access.

After the drivers are installed, restart your computer if prompted.

Step 6 — Set Up Packages for Your Hardware

This step installs the correct version of PyTorch (the AI framework) and other Python packages optimised for your specific hardware. Make sure your virtual environment is active before running this step.

lynxbench-ai setup packages vendor_name

Examples:

# For NVIDIA GPUs:
lynxbench-ai setup packages nvidia

# For AMD GPUs:
lynxbench-ai setup packages amd

# For Intel GPUs:
lynxbench-ai setup packages intel

# For CPU only:
lynxbench-ai setup packages cpu

This may take several minutes as it downloads and installs large AI framework packages (potentially several gigabytes).

Step 7 — Run the Benchmark

You’re ready to run the benchmark! Use the following command, replacing device_type with the correct device type for your hardware:

lynxbench-ai run --device device_type

Examples:

# For NVIDIA GPUs:
lynxbench-ai run --device cuda

# For AMD GPUs (AMD uses the "cuda" device type):
lynxbench-ai run --device cuda

# For Intel GPUs:
lynxbench-ai run --device xpu

# For CPU only:
lynxbench-ai run --device cpu

Why does AMD use cuda? AMD’s ROCm software platform is compatible with NVIDIA’s CUDA interface, so it reports as a cuda device. Don’t worry — the benchmark automatically uses the AMD-specific adapter you installed in the previous step.

What to expect

• The benchmark will confirm your hardware details and ask you to proceed. Type Y and press Enter to continue.
• It runs a series of AI workloads including neural networks and compute tests.
• A full benchmark run takes approximately 15–30 minutes, depending on your hardware.
• You’ll see a progress display showing which tests are running and their status.
• Once complete, a results summary with your scores will be displayed.

Tip: Make sure your computer is plugged in (not running on battery) and avoid running heavy applications during the benchmark for the most accurate results.

Understanding Your Results

When the benchmark finishes, you’ll see a summary table like this:

===========================================================================
BENCHMARK RESULTS
===========================================================================
Model                          Type         Precision  Status      Score
---------------------------------------------------------------------------
dense_matmul                   compute      fp32       success     85.20
distilbert                     inference    fp32       success     72.10
...
---------------------------------------------------------------------------
  Training Score:   72.50
  Inference Score:  81.30
  Compute Score:    90.10
  GT (Overall):     82.40
===========================================================================

• Training Score — How well your hardware performs AI model training tasks.
• Inference Score — How well your hardware performs AI inference (using trained models to make predictions).
• Compute Score — Raw compute performance on mathematical operations.
• GT (Overall) — Your overall benchmark score combining all categories.

Higher scores indicate better performance.

Your results are automatically submitted to the LynxBenchAI platform where you can compare your hardware against others.

Which Device Type Should I Use?

Troubleshooting

“No active Python virtual environment detected”

You forgot to activate your virtual environment. Run:

source lynxbench-ai-env/bin/activate

Then try the command again.

“No vendor adapter installed for device ‘…’”

You need to run the package setup step for your hardware before running the benchmark:

lynxbench-ai setup packages vendor_name

Replace vendor_name with nvidia, amd, intel, or cpu.

“Requested device ‘…’ is not available”

This means the benchmark could not find the hardware you specified. Common causes:

• GPU drivers are not installed. Run lynxbench-ai setup system vendor_name first (see Step 5).
• The wrong device type was used. Double-check the device type table.
• On WSL2: Make sure your Windows GPU drivers are up to date. WSL2 uses the Windows-side GPU driver. WSL version 1 does not support GPU access — you must use WSL2.

JIT compilation error / “build-essential” missing

If the benchmark fails during the initial preflight check with a compilation error, you may need to install build tools:

sudo apt install build-essential

Then try running the benchmark again.

WSL2 + NVIDIA: library path issue

If you are using NVIDIA GPUs under WSL2 and see errors related to missing CUDA libraries, you may need to add the WSL CUDA library path:

export LIBRARY_PATH=/usr/lib/wsl/lib:$LIBRARY_PATH

You can add this line to your ~/.bashrc file to make it permanent.

Python version too old

If pip install lynxbench-ai fails with a message about Python version compatibility, your Python version is below 3.11. Follow the Python installation instructions to update.

Benchmark seems stuck or takes very long

• A full benchmark run can take 15–30 minutes — this is normal.
• Each individual test has built-in timeouts. If a single test encounters an issue, the benchmark will skip it after a timeout and move on to the next test.
• Ensure no other heavy applications are running in the background.

“No matching distribution found for lynxbench-ai-models”

The model data package could not be found. This can happen if:

• You don’t have an internet connection — check your network.
• The package index is temporarily unavailable — try again in a few minutes.

Virtual environment was deactivated

If you closed your terminal or opened a new one, you need to reactivate your virtual environment:

source lynxbench-ai-env/bin/activate

You can verify the environment is active by checking that your prompt starts with (lynxbench-ai-env).

Getting Help

If you’ve followed all the steps above and are still experiencing issues:

1. Check the troubleshooting section above for your specific error message.
2. Make sure you’re using the latest version of LynxBenchAI:

   pip install --upgrade lynxbench-ai
   

3. Contact our support team at [email protected] — include the following information to help us resolve your issue quickly:
   • Your operating system (e.g., Ubuntu 24.04, WSL on Windows 11)
   • Your Python version (python3 --version)
   • Your hardware (GPU model or CPU model)
   • The full error message you received (copy-paste from the terminal)
   • The command you ran that caused the error

Quick Reference

Here is the complete sequence of commands for a typical benchmark run:

# 1. Create and activate a virtual environment (one-time)
python3 -m venv lynxbench-ai-env
source lynxbench-ai-env/bin/activate

# 2. Install LynxBenchAI
pip install lynxbench-ai

# 3. Install hardware drivers (one-time, skip if drivers already installed)
lynxbench-ai setup system nvidia    # replace with your vendor

# 4. Install AI framework packages for your hardware
lynxbench-ai setup packages nvidia  # replace with your vendor

# 5. Run the benchmark
lynxbench-ai run --device cuda      # replace with your device type

LynxBenchAI is developed by TechnoLynx. © TechnoLynx Ltd 2026. All rights reserved.