Zurich Instruments Python API

26.4.0 verified Fri May 01 auth: no python

Official Python API for Zurich Instruments device control and data acquisition. Current version 26.4.0, requires Python ≥3.10. Major releases every few months with API changes; LabOne software version compatibility is critical.

pip install zhinst

Common errors

error ImportError: cannot import name 'Session' from 'zhinst' ↓

cause Incorrect import path; Session is in zhinst.toolkit.

fix

Use: from zhinst.toolkit import Session

error ModuleNotFoundError: No module named 'zhinst.core' ↓

cause Package not installed; older version may have different subpackage structure.

fix

Install latest zhinst: pip install --upgrade zhinst

error zhinst.exceptions.ZIError: Data server not responding. ↓

cause Data Server (ziServer) not running or wrong host/port.

fix

Start LabOne Data Server and ensure 'localhost:8004' is accessible.

Warnings

gotcha The 'zhinst' package requires the LabOne Data Server to be running; the API does not start it automatically. ↓

fix Start the Data Server (ziServer) before running your Python script.

breaking In v23+ the 'zhinst.core' subpackage was reorganized; many classes moved or were renamed (e.g., 'ziDAQServer' instead of 'DataServer'). ↓

fix Use 'zhinst.core.ziDAQServer' and 'zhinst.toolkit.Session'.

gotcha API level must match the LabOne version; using the wrong API level causes silent errors or connection failures. ↓

fix Set api_level=6 for LabOne 23+; check labOne compatibility table.

deprecated The 'zhinst.examples' and 'zhinst.ziPython' modules are deprecated since v22. ↓

fix Use 'zhinst.toolkit' or refer to official examples repository.

Install

pip install zhinst[examples]

Imports

ziSession

wrong

from zhinst.core import Session

correct

from zhinst.toolkit import Session

Session moved to toolkit in v21+

DataServer

wrong

from zhinst import DataServer

correct

from zhinst.core import ziDAQServer

Class name is ziDAQServer, not DataServer

Quickstart

Connect to a Zurich Instruments device via Data Server using toolkit Session.

import os
from zhinst.toolkit import Session

server_host = os.environ.get('ZI_SERVER_HOST', 'localhost')
server_port = int(os.environ.get('ZI_SERVER_PORT', 8004))
api_level = 6

session = Session(server_host, server_port, api_level)
device_id = os.environ.get('ZI_DEVICE_ID', 'dev1234')

a = session.connect_device(device_id)
print('Connected:', a)

# Example: set output amplitude
awg = a.awgs[0]
awg.amplitude(0.5)
print('Amplitude set to:', awg.amplitude())