Install & Compatibility
Where this runs
tested against v3.9.0 · 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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 15.9s · import 0.064s · 220MB
222MB installed
● package 222MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SPSDKError
✓ from spsdk.exceptions import SPSDKError
A base exception for handling SPSDK-related errors.
sdp
✓ from spsdk.sdp import sdp
Accessing the Serial Download Protocol (SDP) communication module for device interaction.
nxpimage
✓ import spsdk.image as nxpimage
The primary module for image processing and generation, replacing older tools like elftosb.
SPSDK is primarily used through its command-line applications (like `blhost`, `nxpimage`, `sdphost`). This quickstart demonstrates invoking `blhost` to read a property from a connected NXP MCU. For direct API interaction, modules such as `spsdk.sdp` or `spsdk.image` would be used.
# Connect to a device via blhost (command-line tool wrapper)
# This example assumes a device is connected and blhost is configured.
# For actual usage, replace 'serial' with 'usb' if applicable and provide correct port/device.
# The blhost command-line utility is typically used directly.
import subprocess
try:
# Example: Get property (e.g., status) from the bootloader
# In a real scenario, you'd provide specific device connection parameters.
command = ['blhost', '-p', 'COMx', 'get-property', '1'] # Replace COMx with your serial port
result = subprocess.run(command, capture_output=True, text=True, check=True)
print("blhost output:")
print(result.stdout)
except subprocess.CalledProcessError as e:
print(f"Error executing blhost: {e}")
print(f"Stderr: {e.stderr}")
except FileNotFoundError:
print("Error: 'blhost' command not found. Ensure SPSDK is installed and your PATH is correct, or use the 'spsdk' wrapper utility.")
# For API usage, you might interact with specific modules directly, e.g., spsdk.sdp
spsdk --version
Debug
Known issues
breakingSPSDK v3.0.0 introduced significant breaking changes. Key applications like `nxpcertgen`, `tphost`, and `tpconfig` were removed or consolidated into `nxpcrypto` and `pfr`. The `--plugin` CLI option was removed, requiring plugins to be installed as Python packages with entry points. Command-line options for `nxpcrypto` (e.g., `-k`/`--private-key` and `-sp`/`--signature-provider` unified to `-s`/`--signer`) and `nxpimage` configurations (e.g., `image_type` replaced by `target_memory`) were also updated.fixRefer to the official `spsdk` Migration Guide for a detailed list of changes and updated usage patterns. Re-evaluate CLI commands and API calls, especially for `nxpcrypto` and `nxpimage` operations.
affects: >=3.0.0 (migration from <3.0.0)
breakingSPSDK v2.0.0 also introduced major breaking changes for users migrating from v1.x. The `elftosb` tool was replaced by `nxpimage`, and `nxpcertgen`/`nxpkeygen` functionalities were moved into `nxpcrypto`. The `--device` (`-d`) parameter was replaced by `--family` (`-f`) for device selection across many tools. Crypto backends were refactored and removed.fixConsult the `spsdk` v2.0.0 release notes and migration guide. Update scripts to use `nxpimage` instead of `elftosb` and `nxpcrypto` for certificate/key operations. Use `--family` for device specification.
affects: >=2.0.0 (migration from <2.0.0)
gotchaFor `blhost` users, a Rust-based alternative called `rblhost` was introduced in SPSDK v3.2.0. `rblhost` offers significantly faster startup times and improved overall performance compared to the Python-based `blhost` implementation. If you experience performance issues with `blhost`, `rblhost` is recommended.fixConsider installing and using `rblhost` (available via `pip install pymboot-rs`) as a drop-in replacement or alongside the Python `blhost` for performance-critical operations. The CLI interface is designed to be compatible.
affects: >=3.2.0
gotchaThe 'Restricted Data Package', which was previously required for certain functionalities, is no longer needed for SPSDK versions 3.2.0 and onwards. Users upgrading from older versions or following outdated documentation might mistakenly try to acquire or install this package.fixIf using SPSDK v3.2.0 or newer, you do not need to download or install the 'Restricted Data Package'. If you encounter references to it, disregard them for current versions.
affects: >=3.2.0
Errors
Common errors & fixes
Building wheel for hidapi (pyproject.toml) did not run successfully.
The `hidapi` package, often a dependency for USB communication features, requires native C compilation during installation. This error typically means that necessary build tools (like C/C++ compilers or development headers) are missing on the system, especially on Windows (e.g., MS Build Tools) or Linux (e.g., `libudev-dev`).
fixEnsure you have the required build tools for your operating system. For Windows, install 'Build Tools for Visual Studio'. For Linux, install `python3-dev` and `libudev-dev` or similar packages (`sudo apt-get install python3-dev libudev-dev`). Try `pip install --no-binary :all: hidapi` as a workaround if the issue persists.
Response status = 10200 (0x27d8) Memory Range Invalid.
This error, often encountered when using `blhost` to program flash, indicates that the target memory region you are trying to write to is either already programmed or protected, or the specified address/range is invalid for the operation.
fixBefore writing to flash, ensure it is properly erased. Use the `blhost flash-erase-region` or `blhost flash-erase-all-unsecure` command to clear the flash memory. Verify the memory addresses and sizes specified in your commands or configuration files are correct for your target device.
Error: 'nxpcertgen' command not found
The `nxpcertgen` application was removed in SPSDK v3.0.0 as part of the consolidation into the `nxpcrypto` module.
fixMigrate your scripts and workflows to use the `nxpcrypto` application for certificate generation and management. Refer to the SPSDK v3.0.0 migration guide for updated command-line syntax and API usage.
Upgrade
Version history
3.9.0latest on PyPI · released May 20, 2026
Audit
Dependencies
No dependency data recorded yet.