Installation

openocd-python requires Python 3.11 or later and a working OpenOCD installation. The library itself has a single dependency: cmsis-svd for SVD register decoding.

Install the package

uv

uv add openocd-python

pip

pip install openocd-python

pipx (CLI only)

pipx install openocd-python

The package installs both the Python library (import openocd) and a CLI tool (openocd-python).

Dependencies

Package	Version	Purpose
cmsis-svd	>= 0.4	SVD file parsing for peripheral register decoding

No other Python dependencies are required. The library uses only the standard library for networking (asyncio), subprocess management, and data types.

Install OpenOCD

openocd-python communicates with OpenOCD over its TCL RPC interface. You need OpenOCD installed and either already running or available on your PATH so the library can spawn it.

Arch Linux

sudo pacman -S openocd

Debian / Ubuntu

sudo apt install openocd

macOS

brew install openocd

Windows

Download the latest release from openocd.org and add the bin directory to your system PATH.

From source

git clone https://github.com/openocd-org/openocd.git
cd openocd
./bootstrap
./configure
make
sudo make install

Verify OpenOCD is installed and accessible:

openocd --version

Note

openocd-python supports OpenOCD 0.11 and later. Some commands (like adapter name) require OpenOCD 0.12+. The library handles version differences automatically, falling back to older command variants when needed.

Verify the installation

After installing both openocd-python and OpenOCD, run a quick check to confirm everything is working.

First, start OpenOCD with your target configuration. For example, with a CMSIS-DAP probe and an STM32F1 target:

openocd -f interface/cmsis-dap.cfg -f target/stm32f1x.cfg

Then, in another terminal, verify the Python package can connect:

from openocd import Session

with Session.connect_sync() as ocd:
    state = ocd.target.state()
    print(f"Target: {state.name}, State: {state.state}")

You can also verify using the CLI:

openocd-python info

This prints the target name, state, transport, adapter, and clock speed.

Tip

If you get a ConnectionError, check that OpenOCD is running and that the TCL RPC port (default 6666) is not blocked by a firewall. The TCL RPC port is distinct from the GDB server port (3333) and the telnet port (4444).

Development installation

To work on openocd-python itself, clone the repository and install the development dependencies:

git clone https://git.supported.systems/ryan/openocd-python.git
cd openocd-python
uv sync --extra dev

The dev extras include:

Package	Purpose
pytest >= 8.0	Test runner
pytest-asyncio >= 0.24	Async test support
ruff >= 0.8	Linter and formatter

Run the test suite (no hardware needed — all tests use a mock OpenOCD server):

uv run pytest

Run the linter:

uv run ruff check src/ tests/

Next steps

• First Connection — connect to OpenOCD and run your first command
• Quick Start — complete working examples for common tasks
• CLI Reference — use the openocd-python command-line tool