Install

Two ways in: run from source, which works everywhere and is what the project is developed against, or take the prebuilt Linux binary if you just want to look at it.

From source

This is the supported path.

git clone https://github.com/Sherin-SEF-AI/CanLab.git
cd CanLab
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cd canlab            # the source root: imports are relative to here
python3 main.py

Python 3.11 or newer. The project is developed and tested on 3.12.

Note the cd canlab

On main the application is run as a script from inside the package directory, not installed as a module. Running python3 canlab/main.py from the repository root will not find its imports.

Prebuilt Linux binary

Each release carries a self-contained x86_64 tarball that needs no Python installation:

tar -xzf CanLab-2.0.0-linux-x86_64.tar.gz
cd CanLab/
./CanLab

Grab it from the latest release. It is unsigned, and it is built from main on x86_64. There is no macOS or Windows binary; run from source on those.

Optional pieces

The application works fully offline with none of these. Each unlocks one feature and is inert until you use it.

What	Install	Needed for
AI providers	`pip install anthropic groq`	The AI ENGINE tab. Or run a local Ollama server, which needs no package and no key.
MDF4 logs	`pip install asammdf`	Opening `.mf4` and `.mdf` captures from CANedge and similar loggers.
openpilot logs	`pip install canlab[openpilot]`	Opening openpilot's `rlog` and `qlog`, plain or compressed. The cereal schema ships with CanLab. A `.zst` log also needs `zstandard`.
MCP server	`pip install mcp`	Exposing the analysis as tools to an MCP client.
Panda	`pip install pandacan`	Using a comma.ai Panda as the interface.

API keys

Keys for the AI providers go in Settings → API KEYS and are stored in the operating system keyring, not in the repository. They can also come from the environment:

export ANTHROPIC_API_KEY="sk-ant-..."
export GROQ_API_KEY="gsk_..."

A local Ollama server needs no key. Nothing is sent anywhere until you enter a key and ask for an analysis; see the AI engine for exactly what leaves the machine.

Hardware interfaces

Live capture goes through python-can, so anything it supports works: socketcan, slcan, gs_usb, pcan, kvaser, vector, virtual and the rest, plus gvret, which CanLab adds itself for SavvyCAN's hardware. Add adapters in Settings → CAN ADAPTERS, which can detect what is plugged in and test it without transmitting, then pick one from the toolbar. See hardware adapters.

On Linux you can practise with no hardware at all using a virtual bus:

sudo modprobe vcan
sudo ip link add dev vcan0 type vcan
sudo ip link set up vcan0
cangen vcan0 -g 5          # optional: generate traffic

Then add an adapter on socketcan / vcan0 and press Connect. The gateway is the one feature that needs two hardware channels.

System requirements

Linux, macOS or Windows with Python 3.11 or newer
4 GB RAM; 8 GB is more comfortable for the machine-learning features
A desktop session. The application is a Qt GUI, though its analysis modules are importable headless and the test suite runs offscreen.

If it will not start

Symptom	Cause and fix
`ImportError: libEGL.so.1` or similar on Linux	Qt needs system graphics libraries that a minimal install lacks. On Debian or Ubuntu: `sudo apt install libegl1 libgl1 libxkbcommon0 libdbus-1-3`.
`ImportError: libpulse.so.0`	Qt Multimedia, used by the timeline's video sync, needs the audio stack. `sudo apt install libpulse0`.
`ModuleNotFoundError: core`	You are running from the wrong directory. `cd canlab` first, then `python3 main.py`.
Nothing decodes, and the signal table stays empty	Check the cantools version. The project pins a version it is tested against in `requirements.txt`; a mismatched one used to fail silently.