Install & Compatibility
Where this runs
tested against v26.5 · 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
py 3.11
✕ build_error
✓ 33.85s
py 3.12
✕ build_error
✓ 36s
py 3.13
✕ build_error
✓ 34.8s
685MB installed
● package 685MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Health
✓ from genie.libs.health import Health
✗ from genie.libs.health import Health
This quickstart demonstrates how to define health checks using a YAML structure, initialize the `Health` object with a device (mocked for this example), and execute the checks. In a real scenario, `my_device` would be an actual connected device loaded from a pyATS testbed file. The example uses `unittest.mock` to make the code runnable without requiring actual device connectivity.
import yaml
from unittest.mock import Mock # For a truly runnable example without a real device
from genie.libs.health.health import Health
# --- 1. Create a mock device and testbed for demonstration ---
# In a real scenario, you would load a testbed from a file:
# from pyats.topology import loader
# testbed = loader.load('path/to/testbed.yaml')
# my_device = testbed.devices['your_device_name']
# Mock a device and its connection/execution methods
mock_device = Mock()
mock_device.name = "my_mock_device"
mock_device.os = "iosxe"
mock_device.connected = False
mock_device.api.execute.return_value = {
"show version": "Cisco IOS XE Software, Version 17.3.4",
"show processes cpu sorted": "CPU utilization for five seconds: 5%/1%; one minute: 4%; five minutes: 3%"
}
# Define connect/disconnect behavior for the mock
def mock_connect():
print(f"Attempting to connect to {mock_device.name} (mocked)...")
mock_device.connected = True
print(f"Successfully connected to {mock_device.name} (mocked).")
mock_device.connect.side_effect = mock_connect
def mock_disconnect():
print(f"Disconnecting from {mock_device.name} (mocked)...")
mock_device.connected = False
mock_device.disconnect.side_effect = mock_disconnect
# Create a mock testbed containing our mock device
mock_testbed = Mock()
mock_testbed.devices = {'my_mock_device': mock_device}
mock_testbed.name = "mock_testbed"
# --- 2. Define a simple health check YAML in-memory ---
health_yaml_content = """
health_check_sections:
section_version_check:
commands:
show version:
- '.*Cisco IOS XE Software.*' # Checks for IOS XE in 'show version' output
section_cpu_usage_check:
commands:
show processes cpu sorted:
- 'CPU utilization for five seconds: [0-9]{1,2}%/' # Checks if CPU is valid percentage
"""
health_data = yaml.safe_load(health_yaml_content)
# --- 3. Initialize and run Health checks ---
try:
# Use the mock device (in a real scenario, this would be from testbed.devices)
my_device = mock_testbed.devices['my_mock_device']
my_device.connect() # This will call our mock_connect function
# Create Health object with the device and parsed health data
health = Health(device=my_device, health_data=health_data)
# Run all defined health checks
print(f"\nRunning health checks on {my_device.name}...")
health_result = health.check_all()
# Print results
print("\nHealth Check Results Summary:")
for section, result in health_result.items():
print(f" Section: '{section}' -> Status: {result['status']}")
if result['status'] == 'Fail':
print(f" Reason: {result.get('reason', 'No specific reason provided.')}")
for command, cmd_result in result.get('commands', {}).items():
if cmd_result.get('status') == 'Fail':
print(f" Command '{command}' failed: {cmd_result.get('reason', 'N/A')}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
if my_device and my_device.connected:
my_device.disconnect()
Debug
Known issues
breakingpyATS and Genie (including genie-libs-health) versions are tightly coupled. Installing incompatible versions can lead to `ImportError`, `AttributeError`, or unexpected behavior.fixAlways install `pyats` and `genie-libs-health` (which pulls `genie`) from the same major release cycle. E.g., if `pyats` is 24.4, ensure `genie` is also from a compatible 24.x release. Check official pyATS documentation for version compatibility matrices.
affects: All versions, especially when upgrading.
gotchaHealth checks require a properly configured pyATS testbed and reachable network devices. Common failures stem from incorrect device IPs, usernames, passwords, or network connectivity issues.fixBefore running health checks, ensure your `testbed.yaml` is accurate and that you can manually connect to the devices using the specified credentials and protocols. Use `pyats run job --testbed testbed.yaml` with a simple connection script to verify connectivity.
affects: All versions.
gotchaHealth check definitions in YAML must strictly adhere to the `genie-libs-health` schema. Syntax errors, incorrect command names, or malformed regex patterns will lead to runtime exceptions or incorrect check results.fixCarefully review your `health_check.yaml` file for correct YAML syntax (indentation, colons, list items) and ensure commands and patterns match device output expectations. Refer to the `genie-libs-health` documentation for the correct YAML schema.
affects: All versions.
gotchaUnderlying Genie operational parsers (`genie.libs.ops`) must successfully parse command output for health checks to function. If a parser fails, the health check for that command will report an error.fixIf a health check fails unexpectedly, debug the underlying command execution and parsing. You can manually run `device.execute('show command')` and `device.parse('show command')` to isolate parsing issues before involving health checks. affects: All versions.
Upgrade
Version history
26.5latest on PyPI · released May 28, 2026
Audit
Dependencies
pyatsrequiredCore test automation framework required to run testbeds and interact with devices.
genierequiredCore Genie library; genie-libs-health is a sub-library leveraging Genie's operational parsers and device abstractions.