{"id":6215,"library":"pyzabbix","title":"PyZabbix","description":"PyZabbix provides a Python interface to the Zabbix API, allowing programmatic interaction with Zabbix monitoring systems. It handles API authentication, requests, and response parsing. The current version is 1.3.1, with releases occurring intermittently, often several months apart.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/lukecyca/pyzabbix","tags":["zabbix","monitoring","api","automation"],"install":[{"cmd":"pip install pyzabbix","lang":"bash","label":"Install PyZabbix"}],"dependencies":[],"imports":[{"note":"The PyPI package name is `pyzabbix`, not `zabbix_api`.","wrong":"from zabbix_api import ZabbixAPI","symbol":"ZabbixAPI","correct":"from pyzabbix import ZabbixAPI"},{"note":"Import for handling API-specific errors returned by the Zabbix server.","symbol":"ZabbixAPIException","correct":"from pyzabbix import ZabbixAPIException"}],"quickstart":{"code":"import os\nfrom pyzabbix import ZabbixAPI, ZabbixAPIException\n\n# Configure Zabbix access via environment variables or replace directly\nZABBIX_URL = os.environ.get('ZABBIX_URL', 'http://localhost/zabbix') # e.g., 'http://your-zabbix-server/zabbix'\nZABBIX_USER = os.environ.get('ZABBIX_USER', 'Admin')\nZABBIX_PASSWORD = os.environ.get('ZABBIX_PASSWORD', 'zabbix') # Default 'zabbix' for Admin user\nZABBIX_TOKEN = os.environ.get('ZABBIX_TOKEN', '') # Optional: for API token authentication\n\n# Initialize zapi outside try-block for finally access\nzapi = None\n\ntry:\n    # Connect to Zabbix API\n    zapi = ZabbixAPI(ZABBIX_URL)\n\n    if ZABBIX_TOKEN:\n        # Authenticate using API token (requires Zabbix 5.0+ and pyzabbix >= 1.0.0)\n        zapi.login(api_token=ZABBIX_TOKEN)\n        print(\"Authenticated using API Token.\")\n    else:\n        # Authenticate using username and password\n        zapi.login(ZABBIX_USER, ZABBIX_PASSWORD)\n        print(f\"Authenticated as user: {ZABBIX_USER}\")\n\n    print(f\"Connected to Zabbix API version: {zapi.api_version()}\")\n\n    # Example: Fetch Zabbix server info\n    version_info = zapi.apiinfo.version()\n    print(f\"Zabbix Server Version: {version_info}\")\n\n    # Example: Fetch some hosts\n    # 'output' determines which fields are returned, 'selectInterfaces' specifies linked data\n    hosts = zapi.host.get(output='extend', selectInterfaces=['interfaceid', 'ip', 'port'])\n    print(f\"Found {len(hosts)} hosts.\")\n    if hosts:\n        print(f\"First host: {hosts[0]['host']} (IP: {hosts[0]['interfaces'][0]['ip']})\")\n\nexcept ZabbixAPIException as e:\n    print(f\"Error interacting with Zabbix API: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Ensure proper logout if authenticated\n    if zapi and zapi.is_authenticated:\n        zapi.logout()\n        print(\"Logged out from Zabbix API.\")\n","lang":"python","description":"This quickstart demonstrates how to connect to the Zabbix API, authenticate using either username/password or an API token (if provided via environment variables), retrieve basic Zabbix server information, and list hosts. It includes error handling for API-specific issues and ensures proper session cleanup with `logout()`."},"warnings":[{"fix":"Review authentication methods and ensure compatibility with auto-detected API versions. Consider updating authentication to use API tokens if applicable (Zabbix 5.0+).","message":"Version 1.0.0 introduced significant changes including API token support and automatic API version detection. Code relying on older manual API version specification or lacking token handling may require updates.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Consult the `pyzabbix` GitHub page or changelog for explicit Zabbix server version compatibility. Upgrade `pyzabbix` if your Zabbix server has been updated to a newer major version.","message":"Compatibility with Zabbix server versions is crucial. PyZabbix targets specific Zabbix API versions. Ensure your `pyzabbix` version supports your Zabbix server's API version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always wrap `pyzabbix` API calls in `try...except ZabbixAPIException` blocks to gracefully handle Zabbix API errors.","message":"Zabbix API errors are encapsulated in `ZabbixAPIException`. Failure to catch this specific exception can lead to unhandled errors, especially when making API calls that might fail (e.g., non-existent IDs, insufficient permissions).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `zapi.logout()` is called in a `finally` block or at the end of your script to prevent stale sessions.","message":"Authentication management requires careful handling. While `pyzabbix` abstracts `login()`, it's vital to explicitly call `zapi.logout()` after operations or use a context manager (if implemented in future versions) to ensure sessions are properly terminated, especially for long-running applications.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}