Install & Compatibility
Where this runs
tested against v0.8.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.258s · 20.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.230s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ResourceManager
✓ import pyvisa
rm = pyvisa.ResourceManager('@py')
✗ import pyvisa
rm = pyvisa.ResourceManager()
When using `pyvisa-py`, you must explicitly specify the '@py' backend for ResourceManager. Otherwise, PyVISA will attempt to load a system-installed VISA library (e.g., NI-VISA) by default, which may not be present or desired.
This quickstart demonstrates how to initialize the `ResourceManager` specifically with the `pyvisa-py` backend, list available instrument resources, and attempt to open and query a resource. Note that connecting to and querying a real instrument requires the instrument to be physically connected and the corresponding optional dependencies (e.g., `PySerial` for serial, `PyUSB` for USB) to be installed. Without a connected instrument or emulator, `list_resources()` might return an empty tuple.
import pyvisa
# Initialize the Resource Manager with the PyVISA-py backend
# This tells PyVISA to use the pure Python implementation.
rm = pyvisa.ResourceManager('@py')
# List available resources (instruments)
# The output will vary based on connected and supported hardware/emulators
resources = rm.list_resources()
print(f"Available resources: {resources}")
# Example of opening a (possibly simulated) instrument
# This line might fail if no such resource exists or is not properly configured
# For demonstration, we'll try to open a generic ASRL resource if available.
# Replace 'ASRL1::INSTR' with an actual resource from your 'resources' list.
if resources:
try:
# Choose the first resource or a known one, e.g., 'ASRL1::INSTR'
# Ensure the chosen resource type has its optional dependencies installed (e.g., PySerial for ASRL)
instrument_address = resources[0]
# Fallback to a common dummy address if real ones aren't found, for demonstration
if not instrument_address.startswith(('ASRL', 'USB', 'TCPIP', 'GPIB')):
instrument_address = 'ASRL1::INSTR' # This will likely fail without PySerial/a real ASRL port
inst = rm.open_resource(instrument_address)
print(f"Successfully opened: {instrument_address}")
# Example: Query instrument identification (standard SCPI command)
# This will likely only work if you have a real instrument or a simulator running
try:
idn = inst.query('*IDN?')
print(f"Instrument IDN: {idn.strip()}")
except pyvisa.errors.VisaIOError as e:
print(f"Could not query *IDN? on {instrument_address}: {e}")
finally:
inst.close()
print(f"Closed {instrument_address}")
except pyvisa.errors.VisaIOError as e:
print(f"Could not open resource {instrument_address}: {e}")
except IndexError:
print("No resources found to open.")
else:
print("No resources found by PyVISA-py backend.")
Debug
Known issues
gotchaUsing PyVISA-py within a Virtual Machine (VM) or Docker container can lead to unexpected timeouts or connectivity issues when accessing hardware-dependent resources like USB or GPIB. VMs might not properly forward hardware responses, and Docker containers might disconnect idle connections.fixFor VMs, consult the VM manual for proper hardware passthrough/configuration. For Docker (especially with TCP/IP instruments), consider enabling keepalive packets for the VISA session using `inst.set_visa_attribute(pyvisa.constants.ResourceAttribute.tcpip_keepalive, True)` to prevent idle connections from being dropped.
affects: All versions
gotchaPyVISA-py's ability to communicate with different instrument types (Serial, USB, GPIB) depends on specific optional Python libraries (e.g., PySerial, PyUSB, linux-gpib, gpib-ctypes). If these are not installed, PyVISA-py may only be able to access TCPIP resources.fixInstall the relevant optional dependencies for the instrument interface you intend to use (e.g., `pip install pyvisa-py pyserial pyusb`). Refer to the PyVISA-py documentation for a full list of dependencies per resource type.
affects: All versions
gotchaFor USB instruments, `PyUSB` (a dependency for PyVISA-py's USB support) requires an underlying USB driver library (e.g., `libusb`). On Unix-like systems, `udev` rules may need to be modified to grant non-root users access to USB devices. On Windows, you might need to uninstall USBTMC-specific drivers and install a generic driver.fixEnsure `libusb` or a compatible USB driver library is installed. Consult `PyUSB` documentation and your operating system's guides for specific driver installation and permissions setup (e.g., `udev` rules on Linux).
affects: All versions
breakingWhile not directly in `pyvisa-py`, the underlying `PyVISA` library introduced significant breaking changes in versions 1.5 and 1.6. Key changes include the removal of the direct `pyvisa.instrument()` function in favor of `ResourceManager().open_resource()` and modifications to `ask()`/`query()` methods and event handler arguments.fixUpdate your code to use `pyvisa.ResourceManager().open_resource()` instead of `pyvisa.instrument()`. Replace `instrument.ask()` with `instrument.query()`. Review PyVISA's migration guide if upgrading from versions older than 1.5.
affects: PyVISA versions 1.5 and 1.6+
gotchaIncorrect `read_termination` or `write_termination` characters, or an incorrect baud rate, are common issues when communicating with serial instruments. The default baud rate is often 9600, but instrument manuals should be consulted.fixAlways check your instrument's manual for the correct baud rate, stop bits, parity, and flow control settings. Explicitly set `instrument.read_termination` and `instrument.write_termination` to match the instrument's requirements (e.g., `\n`, `\r`, or an empty string for no termination).
affects: All versions
Errors
Common errors & fixes
visa.errors.LibraryError: Could not find the VISA library.
PyVISA could not locate any installed VISA backend, including pyvisa-py, or the specified backend ('@py') is not available or properly configured.
fixEnsure pyvisa-py is installed (`pip install pyvisa-py`) and, if using a specific backend, explicitly initialize ResourceManager with `rm = visa.ResourceManager('@py')`. ModuleNotFoundError: No module named 'pyvisa.py_wrapper'
The pyvisa-py package's internal `py_wrapper` module, necessary for its functionality, is not correctly installed or accessible in the Python environment, often due to an incomplete or corrupted installation.
fixReinstall pyvisa-py to ensure all components are properly installed: `pip install --upgrade --force-reinstall pyvisa-py`.
visa.errors.VisaIOError: VI_ERROR_RSRC_NFOUND
PyVISA, using the pyvisa-py backend, could not find a resource matching the specified resource string, indicating the device is either not connected, not recognized by the operating system, or the resource string is incorrect.
fixVerify the device is connected, powered on, and recognized by the operating system. Use `rm.list_resources()` to enumerate available resources and ensure the provided resource string is accurate.
Upgrade
Version history
0.8.1latest on PyPI · released Sep 4, 2025
Audit
Dependencies
pyvisarequiredPyVISA-py is a backend for PyVISA, which provides the high-level API for instrument control.
PySerialoptionalRequired for interfacing with Serial (ASRL) instruments.
PyUSBoptionalRequired for interfacing with USB (USB INSTR/RAW) instruments. Also requires an underlying USB driver library like libusb.
linux-gpiboptionalOptional for GPIB instruments, specifically on Linux.
gpib-ctypesoptionalOptional for GPIB instruments on Windows and Linux.
psutiloptionalOptional for discovering VXI-11 devices on all network interfaces. Without it, discovery is limited to the default interface.
zeroconfoptionalOptional for HiSLIP and VICP device discovery, which relies on mDNS.
pyvicpoptionalOptional for enabling the Teledyne LeCroy proprietary VICP protocol.