pyocd

library0.45.1pypypi✓ verified 25d ago

pyOCD is an open-source Python library and command-line tool for programming and debugging Arm Cortex-M microcontrollers using various debug probes such as CMSIS-DAP, J-Link, and ST-Link. It provides a flexible Python API for low-level target control, suitable for automated testing and CI/CD workflows, alongside a powerful command-line interface for common operations like GDB server, flashing, and erasing. Currently at version 0.44.0, pyOCD maintains an active development cycle with several minor releases annually.

devops testing data

pip install pyocd

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYOCD

pyocd

devopspythonv0.45.1

Install

5.0s avg

Import

1525ms

Disk

90MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.45.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 5.0s · import 1.525s · 93MB

90MB installed

● package 90MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConnectHelper

✓ from pyocd.core.helpers import ConnectHelper

FileProgrammer

✓ from pyocd.flash.file_programmer import FileProgrammer

This quickstart demonstrates how to connect to a debug probe, halt the target microcontroller, program a firmware image (HEX format in this example), and then reset and run the target using the pyOCD Python API. Ensure a debug probe is connected and `your_firmware.hex` is replaced with an actual firmware file or created as a dummy for testing.

import time import logging import os from pyocd.core.helpers import ConnectHelper from pyocd.flash.file_programmer import FileProgrammer logging.basicConfig(level=logging.INFO) FIRMWARE_PATH = "your_firmware.hex" # Replace with the actual path to your firmware # Create a dummy firmware file for demonstration if it doesn't exist if not os.path.exists(FIRMWARE_PATH): with open(FIRMWARE_PATH, "w") as f: f.write(":100000000000000000000000000000000000000000\n") # Minimal valid HEX file try: # Connect to the target with the first found probe. # For a specific probe, use unique_id="E6616407E3646B29" # For a specific target, use options={"target_override": "nrf52840"} with ConnectHelper.session_with_chosen_probe() as session: target = session.target board_id = session.board.unique_id if session.board else "Unknown" logging.info(f"Connected to probe: {board_id}, target: {target.name}") # Halt the target target.halt() logging.info("Target halted.") # Program firmware logging.info(f"Programming {FIRMWARE_PATH}...") FileProgrammer(session).program(FIRMWARE_PATH) logging.info("Programming complete.") # Reset and run target.reset_and_run() logging.info("Target reset and running.") # Allow the target to run for a short period (demonstration) time.sleep(1) except Exception as e: logging.error(f"An error occurred: {e}") logging.info("Please ensure a debug probe is connected and compatible firmware is specified.")

pyocd --version

Debug

Known issues

breakingPython 3.7 is no longer supported starting with pyOCD v0.37.0. Projects must use Python 3.8 or later.

fix

Upgrade your Python environment to 3.8 or a newer compatible version.

affects: >=0.37.0

breakingThe `run` subcommand introduced significant changes and new configurations for RTT, SystemView, and Semihosting in versions 0.42.0 and 0.43.0. Older scripts relying on specific `run` subcommand behaviors or arguments might need updates.

fix

Review the official documentation for the `run` subcommand and update scripts to use the new features and configuration methods, particularly for RTT (`server` mode renamed from `telnet` in v0.44.0) and SystemView.

affects: >=0.42.0

breakingFlash programming operations were split into separate erase and program operations starting from v0.44.0. Direct flash programming might now require explicit erase calls depending on the workflow.

fix

Adjust custom flash programming scripts to account for the explicit erase/program separation as detailed in the v0.44.0 changelog.

affects: >=0.44.0

breakingThe RTT channel mode `telnet` was renamed to `server` in pyOCD v0.44.0.

fix

Update any configurations or scripts referencing the `telnet` RTT channel mode to use `server` instead.

affects: >=0.44.0

gotchaThe Python API is considered unstable prior to version 1.0, with planned breaking changes to align with PEP8 naming conventions. Additionally, the command-line tools are planned to be merged into a single utility in future 1.0 releases.

fix

While the `0.x` API is stable, be prepared for potential breaking changes when upgrading to version 1.0 and beyond. Refer to the release notes for migration guides.

affects: <1.0

gotchaInstallation of the `libusb` binary shared library is a manual, OS-dependent step and is not handled automatically by pip. Without it, pyOCD cannot communicate with USB debug probes.

fix

Install `libusb` according to your operating system's instructions: `brew install libusb` on macOS, usually pre-installed on Linux, and manual DLL placement on Windows (matching Python's architecture).

affects: All versions

gotchaOn Linux, without proper udev rules, pyOCD might require root privileges (sudo) to detect and access debug probes. This is a common permission issue.

fix

Add appropriate udev rules for your debug probe to allow unprivileged user access. An example for NXP FRDM-K64F involves creating `/etc/udev/rules.d/50-mbed.rules` with `SUBSYSTEM=="usb", ATTR{idVendor}=="0d28", ATTR{idProduct}=="0204", MODE:="666"`. Check `dmesg` for your device's Vendor/Product IDs.

affects: All versions

Errors

Common errors & fixes

pyocd: command not found

The pyOCD executable is not in your system's PATH, or pyOCD was not installed into an accessible environment.

fix

Ensure pyOCD is installed globally or in your virtual environment using `pip install pyocd`, and that your system's PATH includes the directory where Python scripts are installed.

Could not find any debug probes

The debug probe (e.g., J-Link, ST-Link, CMSIS-DAP) is either not physically connected, not recognized by the operating system, or necessary drivers/permissions are missing.

fix

Verify the debug probe is physically connected, ensure specific USB drivers are installed for your probe, and check for udev rules (Linux) or administrative privileges (Windows/macOS) if required.

ModuleNotFoundError: No module named 'pyocd'

The `pyocd` library is not installed in the active Python environment or the environment is not correctly activated.

fix

Install pyOCD using `pip install pyocd` in your active Python environment.

pyocd.core.exceptions.TargetError: Failed to reset target

pyOCD failed to successfully reset the target microcontroller, often due to issues with the debug probe connection, target power, or corrupted firmware preventing proper debug access.

fix

Verify all physical connections to the target, ensure the target is powered correctly, try cycling power to the target, and ensure debug probe firmware is up-to-date.

Upgrade

Version history

0.45.1latest on PyPI · released Jul 21, 2026

Audit

Dependencies

PythonrequiredRequired for execution

libusbrequiredBinary shared library backend for USB communication with debug probes

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/pyocd/pyOCD ↗

packagehttps://pypi.org/project/pyocd/ ↗

homepagehttps://pyocd.io ↗

docshttps://pyocd.io//docs ↗

changeloghttps://github.com/pyocd/pyOCD/releases ↗