obd-diag

See what your car's check engine light is about, on Linux.

Plug a cheap ELM327 adapter into the OBD-II port, and obd-diag reads the trouble codes, explains them in plain words and shows what the engine is doing right now. Desktop app and command line, in English and German, no account and no cloud.

English · Deutsch

Why obd-diag

• Read-only by design. obd-diag only asks, it never changes anything in the car. Every command passes an allowlist taken from the ELM327 datasheet and SAE J1979; anything else is refused before it reaches the adapter. No coding, no flashing, no service functions.
• Answers, not hex. Trouble codes come with an offline description and a rough urgency (from "keep an eye on it" to "avoid driving").
• Buying a used car? The used-car check shows whether someone cleared the trouble codes shortly before the viewing, using the counters that clearing resets.
• Tested on a real car (Mercedes A 180 d) and, without hardware, against the datasheet, third-party adapter logs and python-OBD, with around 2000 automated tests.

What it shows

Try it without a car

The demo mode plays back a recorded Mercedes A 180 d, no adapter needed:

pipx install 'obd-diag[gui]'
obd-diag-gui --demo

Install

pipx install 'obd-diag[gui]'              # any distribution (PyPI); without [gui]: command line only
yay -S obd-diag                           # Arch Linux (AUR)
flatpak install --user obd-diag.flatpak   # bundle from the GitHub release

Needs Linux and Python 3.12 or newer. Details, udev rule and serial port permissions: Installation.

At the car

You need an ELM327-compatible adapter (USB or Bluetooth serial) and a car with OBD-II (petrol from 2001, diesel from 2004 in the EU; 1996 in the US).

obd-diag setup-check                      # finds the adapter, checks permissions and baud rate
obd-diag diagnose --port /dev/ttyUSB0     # ignition on, engine off
obd-diag live --port /dev/ttyUSB0         # live data, Ctrl+C to stop
obd-diag-gui                              # or all of it in the desktop app

Before the first drive with a laptop on the passenger seat, read First test at the car.

What it does not do

obd-diag talks to the standardised emissions diagnosis (OBD-II). It does not reach airbag, ABS or comfort modules, and it does not code, flash or reset service intervals. Clearing trouble codes is built in, with checks and a backup, but stays locked for now. Next on the roadmap: Bluetooth LE adapters and reading the fault memory of all control units via UDS, still read-only.

Documentation

Everything else is on the website, in English and German: every command and option, the user interface, common problems, how the tool talks to the adapter (with a real trace explained line by line) and the safety concept.

Contributing

Bug reports and traces from other cars are very welcome, especially from makes other than Mercedes. --trace records the adapter communication; it contains the VIN, so please remove it before sharing.

uv sync && uv run python tools/build_dtc_db.py
uv run pytest

Rules, tests and translations: Contributing, changes: CHANGELOG.md (German).

License

MIT. Trouble code texts from OBDex.