Install & Compatibility
Where this runs
tested against v0.25 · 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
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
iio
✓ import iio
✗ import iio
This quickstart demonstrates how to establish a connection to an IIO context (local or remote), scan for available devices and their channels, and perform a basic buffered read operation. It includes error handling for common connection issues.
import iio
import os
# Try to connect to a local or remote IIO context
# Use 'local' for devices on the same machine, or 'ip:address' for remote
# For testing without hardware, you can often use 'dummy'
# The URI can also be 'usb', 'serial', or an IP address (e.g., 'ip:192.168.1.100')
# For robust examples, use an environment variable or default to local
uri = os.environ.get('IIO_URI', 'local')
try:
ctx = iio.Context(uri)
print(f"Connected to IIO context: {ctx.description}")
# Scan for available devices
print("\nAvailable IIO devices:")
for dev in ctx.devices:
print(f" - Device: {dev.name} (ID: {dev.id})")
for channel in dev.channels:
print(f" - Channel: {channel.name} (ID: {channel.id}, Output: {channel.output})")
# Example: Try to read an attribute if it exists
try:
sample_rate = channel.attrs['sampling_frequency'].value
print(f" Sampling Frequency: {sample_rate}")
except KeyError:
pass
except Exception as e:
print(f" Error reading attribute: {e}")
# Example: Find a specific device (replace with a known device on your system)
# For a dummy device, you might use 'iio:device0'
target_device_name = os.environ.get('IIO_TARGET_DEVICE', 'iio:device0')
device = ctx.find_device(target_device_name)
if device:
print(f"\nFound target device: {device.name}")
# Example: Set a device attribute (e.g., gain, if supported)
# try:
# if 'gain_control' in device.attrs:
# device.attrs['gain_control'].value = 'manual'
# print(f"Set gain_control on {device.name}")
# except KeyError:
# pass
# except Exception as e:
# print(f"Error setting device attribute: {e}")
# Example: Enable a channel and create a buffer to read data
input_channel = device.find_channel('voltage0', is_output=False)
if input_channel:
input_channel.enabled = True
print(f"Enabled channel: {input_channel.name}")
buffer = iio.Buffer(device, 4096) # 4096 samples
print(f"Created buffer for {device.name}")
# Read data (replace with actual processing)
data = buffer.read()
print(f"Read {len(data)} bytes from buffer.")
buffer.close()
else:
print(f"Channel 'voltage0' not found on {device.name}.")
else:
print(f"Target device '{target_device_name}' not found.")
ctx.close()
print("\nDisconnected from IIO context.")
except Exception as e:
print(f"Failed to connect to IIO context or interact with devices: {e}")
print("Ensure the libiio C library is installed and IIO devices are available/accessible.")
Debug
Known issues
breakingThe `pylibiio` Python bindings (version 0.x) are designed for compatibility with the `libiio` C library versions 0.x. Using `pylibiio` 0.x with `libiio` v1.x (a newer, in-development major version) can lead to runtime errors or unexpected behavior due to API changes.fixEnsure your installed `libiio` C library version matches the `0.x` series, typically `v0.25` or `v0.26` for compatibility with `pylibiio 0.25`. Avoid mixing major versions.
affects: pylibiio 0.x with libiio 1.x
gotchaOn Linux, if `pylibiio` is installed from source (rather than pip), or if `libiio`'s Python bindings are not in a standard path, you may encounter `ModuleNotFoundError` or other import issues unless `PYTHONPATH` is correctly configured.fixAdd the installation directory (e.g., `/usr/lib/python3.x/site-packages`) to your `PYTHONPATH` environment variable: `export PYTHONPATH=$PYTHONPATH:/usr/lib/python{python-version}/site-packages`. affects: All versions on Linux when installed from source or in non-standard locations
deprecatedPast releases of `pylibiio` (e.g., 0.23, 0.21.1) were 'yanked' from PyPI due to critical issues like a broken `find_channel` method or mismatches with required `libiio` C library versions. While these versions are no longer directly installable via `pip`, it highlights the importance of using the latest stable `pylibiio` version and matching `libiio` C library.fixAlways use the latest stable version of `pylibiio` from PyPI and ensure your underlying `libiio` C library is also up-to-date and compatible.
affects: 0.21.1, 0.23
Upgrade
Version history
0.25latest on PyPI · released Aug 10, 2023
Audit
Dependencies
libiiorequiredpylibiio is a Python binding for the libiio C library. The C library must be installed separately at the system level. It is not bundled with the pip package.
libusboptionalRequired for USB backend communication with IIO devices.
avahi-daemonoptionalRequired for network (mDNS/Bonjour) device discovery on Linux hosts.
libserialportoptionalRequired for serial backend communication with IIO devices.