Install & Compatibility
Where this runs
tested against v2.0.4 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.461s · 27.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 2.7s · import 0.412s · 30MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ZabbixAPI
✓ from zabbix_utils import ZabbixAPI
For synchronous interaction with the Zabbix API.
AsyncZabbixAPI
✓ from zabbix_utils import AsyncZabbixAPI
For asynchronous interaction with the Zabbix API, requiring an async event loop.
Sender
✓ from zabbix_utils import Sender
For sending data to Zabbix server or proxy, similar to zabbix_sender utility.
Getter
✓ from zabbix_utils import Getter
For retrieving data from Zabbix agents, similar to zabbix_get utility.
This quickstart demonstrates how to establish a connection to the Zabbix API using `ZabbixAPI` class, authenticate with username and password (or token), and perform a basic API call to retrieve a list of hosts. It prioritizes environment variables for credentials, falling back to defaults if not set. Remember to replace placeholder values with your actual Zabbix server URL and credentials. For asynchronous operations, use `AsyncZabbixAPI` and `await` with an `async def` function.
import os
from zabbix_utils import ZabbixAPI
# Configure Zabbix API access using environment variables
ZABBIX_URL = os.environ.get('ZABBIX_URL', 'http://127.0.0.1/zabbix')
ZABBIX_USER = os.environ.get('ZABBIX_USER', 'Admin')
ZABBIX_PASSWORD = os.environ.get('ZABBIX_PASSWORD', 'zabbix')
# Initialize ZabbixAPI instance and log in
try:
api = ZabbixAPI(url=ZABBIX_URL)
api.login(user=ZABBIX_USER, password=ZABBIX_PASSWORD)
print(f"Successfully logged into Zabbix API at {ZABBIX_URL}")
# Example: Fetch all hosts
hosts = api.host.get(output=['hostid', 'name'])
if hosts:
print("\nKnown hosts:")
for host in hosts:
print(f" ID: {host['hostid']}, Name: {host['name']}")
else:
print("No hosts found.")
except Exception as e:
print(f"Error connecting to Zabbix API: {e}")
finally:
# Always log out to close the session if logged in
if 'api' in locals() and api.is_logged_in:
api.logout()
print("Logged out from Zabbix API.")
Debug
Known issues
breakingThe format of responses from the `Sender` and `Getter` classes changed significantly in version 1.1.0. Existing code parsing these responses will break.fixReview the new response format for `Sender` and `Getter` methods and update parsing logic accordingly. Refer to official documentation or examples for the new structure.
affects: >=1.1.0
breakingVersion 2.0.0 introduced asynchronous modules (`AsyncZabbixAPI`, `AsyncSender`, `AsyncGetter`). While synchronous modules still exist, users migrating to async will need to rewrite their code using `await` and an async event loop.fixFor asynchronous operations, import `AsyncZabbixAPI` (or `AsyncSender`, `AsyncGetter`), define an `async` function, and `await` all API calls. Install `aiohttp` for async dependencies.
affects: >=2.0.0
breakingSupport for HTTP authentication was discontinued for Zabbix server versions 7.2 and newer starting from `zabbix-utils` version 2.0.2.fixUpgrade your Zabbix server to use API tokens for authentication or downgrade `zabbix-utils` if compatible with your Zabbix server version and prior authentication methods.
affects: >=2.0.2 (when connecting to Zabbix >=7.2)
deprecatedOfficial support for Zabbix server version 5.0 was discontinued with the release of `zabbix-utils` version 2.0.3.fixIt is highly recommended to upgrade your Zabbix server to a currently supported version to ensure compatibility and receive security updates.
affects: >=2.0.3
gotchaZabbix API methods with names that are Python keywords (e.g., `import`, `get`) require an underscore suffix when called through the `ZabbixAPI` object to avoid syntax errors.fixWhen calling such methods, append an underscore. For example, `api.configuration.import_()` instead of `api.configuration.import()`.
affects: All
gotchaA bug causing timeout parameters to be ignored for connections was fixed in version 2.0.4, which could lead to scripts hanging indefinitely on network issues in older versions.fixUpgrade to `zabbix-utils` version 2.0.4 or newer to ensure connection timeouts are respected and prevent scripts from hanging.
affects: <2.0.4
Errors
Common errors & fixes
zabbix_utils.exceptions.ProcessingError: Unexpected response was received from Zabbix.
This error typically indicates that the Zabbix server responded with something unexpected or invalid, often due to misconfiguration, network issues, or the Zabbix server being unavailable or returning an error status.
fixVerify that the Zabbix server URL is correct, the Zabbix API is accessible, and the server is running. Check Zabbix server logs for any related errors.
The connection to zabbixsrv.example.net:10051 timed out after 10 seconds while trying to send.
This indicates a network connectivity issue or that the Zabbix server/proxy is not listening on the specified host and port (default 10051 for sender). A firewall might also be blocking the connection.
fixEnsure the Zabbix server/proxy is running, the host and port are correct, and no firewalls are blocking the connection between your script and the Zabbix server/proxy. Consider increasing the timeout if latency is expected.
Zabbix API version mismatch. The Zabbix server version (X.Y) is not officially supported by this library version (A.B).
Your `zabbix-utils` library version does not officially support the Zabbix server version you are trying to connect to. This can happen when a new Zabbix server version is released before the library is updated.
fixUpgrade `zabbix-utils` to the latest version (`pip install --upgrade zabbix-utils`). If the latest version still doesn't support your Zabbix server, you might need to use the `skip_version_check=True` parameter in `ZabbixAPI` (use with caution) or wait for a library update.
Upgrade
Version history
2.0.4latest on PyPI · released Dec 17, 2025
Audit
Dependencies
aiohttpoptionalRequired for asynchronous API interactions (AsyncZabbixAPI, AsyncSender, AsyncGetter).