{"id":9007,"library":"genie-libs-ops","title":"Genie Libs Ops","description":"Genie Libs Ops (Operational State) is a core sub-component of the Cisco pyATS and Genie framework, current version 26.3. It provides a robust, network OS-agnostic abstraction layer to retrieve and model the operational state of network devices. This library is crucial for network test automation, offering structured data representation of device operational states (e.g., BGP, OSPF, interfaces) that can be learned, compared, and validated. Releases are frequent, typically monthly or bi-monthly, aligning with the broader pyATS/Genie ecosystem.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/genielibs","tags":["network automation","cisco","devnet","pyats","genie","operational state","telemetry","networking"],"install":[{"cmd":"pip install genie-libs-ops","lang":"bash","label":"Install only Ops library"},{"cmd":"pip install genie","lang":"bash","label":"Recommended: Install Genie (includes ops)"},{"cmd":"pip install pyats[full]","lang":"bash","label":"Full pyATS/Genie installation (includes ops)"}],"dependencies":[{"reason":"Core framework that provides the testbed management, device connections, and overall Genie infrastructure. genie-libs-ops is a sub-component of Genie.","package":"genie","optional":false},{"reason":"The underlying Python Automation Test System framework upon which Genie is built.","package":"pyats","optional":false}],"imports":[{"note":"Example import for a specific operational state (BGP) on a specific OS (IOS-XE). Path varies by feature and OS.","symbol":"Bgp","correct":"from genie.libs.ops.bgp.iosxe.bgp import Bgp"},{"note":"Used to load testbed YAML files, a common prerequisite for using Genie Ops objects.","symbol":"loader","correct":"from pyats.topology import loader"}],"quickstart":{"code":"import os\nfrom pyats.topology import loader\nfrom genie.libs.ops.bgp.iosxe.bgp import Bgp # Example: import BGP ops for IOS-XE\nimport pprint\n\n# Ensure a testbed.yaml exists or create a dummy one for demonstration\n# In a real scenario, this would connect to a live device.\n# For local testing, mock the connection or use a local testbed file.\n# Example testbed.yaml content (place in same directory as script):\n# devices:\n#   Router1:\n#     os: iosxe\n#     type: router\n#     connections:\n#       cli:\n#         protocol: ssh\n#         ip: 10.1.1.1 # Replace with actual device IP\n#         port: 22\n#     credentials:\n#       default:\n#         username: cisco\n#         password: cisco\n\ntry:\n    testbed = loader.load(os.environ.get('TESTBED_FILE', 'testbed.yaml'))\n    device = testbed.devices.get('Router1')\n    if not device:\n        raise ValueError(\"Device 'Router1' not found in testbed.yaml\")\n\n    # In a real scenario, device.connect() would be called here:\n    # device.connect(log_stdout=False)\n\n    # Instantiate the Ops object for BGP on the device\n    bgp_ops = Bgp(device=device)\n\n    # Learn the operational state of BGP\n    # This would execute 'show' commands on the device and parse output\n    # For this example, it will run against a mocked device or fail if no connection\n    bgp_ops.learn()\n\n    print(f\"\\nLearned BGP operational state for {device.name}:\")\n    pprint.pprint(bgp_ops.info)\n\n    # Example: Check if BGP is configured in VRF default\n    if 'vrf' in bgp_ops.info and 'default' in bgp_ops.info['vrf']:\n        print(\"\\nBGP is configured in VRF 'default'.\")\n    else:\n        print(\"\\nBGP not found in VRF 'default' or not configured.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"\\nEnsure 'testbed.yaml' is correctly configured and device is reachable, or mock device interaction for testing.\")","lang":"python","description":"This quickstart demonstrates how to use `genie.libs.ops` to load a testbed, instantiate an operational state object (e.g., BGP for IOS-XE), learn the device's operational state, and access the structured data. A `testbed.yaml` file is expected for device connection details. For actual execution, ensure device connectivity or mock the device behavior."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer. Python 3.8+ is generally recommended for the latest Genie releases.","message":"Python 3.6 support officially ended after April 2022. Users on older Python versions (3.6 and below) must upgrade to Python 3.7+ (preferably 3.8+) to use recent versions of Genie Libs Ops and the broader pyATS/Genie framework.","severity":"breaking","affected_versions":"<=22.3"},{"fix":"Use `pip install genie` or `pip install pyats[full]` to ensure all necessary components are installed.","message":"While `pip install genie-libs-ops` is possible, it is highly recommended to install the full `genie` or `pyats[full]` package. `genie.libs.ops` relies heavily on other components of the `genie` and `pyats` ecosystem (e.g., connection handlers, parsers). Installing only `genie-libs-ops` can lead to missing functionalities and runtime errors if dependencies are not met.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the Genie Models documentation to find the exact command string and supported features for each OS. Use the full, precise command as expected by the parser.","message":"When using `device.parse()` or `genie learn` for network commands, shorthand or non-standard command variations might not be recognized by built-in parsers, resulting in 'Could not find parser' or 'ambiguous' errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to a more recent version of Genie/pyATS (19.9 or newer) where these concurrency issues have been addressed. If upgrading is not immediately possible, use a single worker/thread for Genie operations.","message":"Older versions of Genie (pre-19.9) had issues with multi-threaded execution, particularly when integrated with frameworks like Nornir using multiple workers. This could lead to parsing or operational state learning failures.","severity":"deprecated","affected_versions":"<19.9"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Perform a clean re-installation: `pip uninstall -y pyats genie genie.libs.ops` followed by `pip install --no-cache-dir genie` (or `pyats[full]`). Ensure you are in a clean virtual environment.","cause":"This error typically occurs after an upgrade of pyATS/Genie, indicating that internal plugin structures or symbols have changed, and cached or older modules are being used.","error":"ImportError: cannot import name 'Csr1000vPatterns'"},{"fix":"Verify the exact output of the `show` command on the device. Check the Genie Models documentation if there's an updated parser or if your device's output deviates significantly. You may need to create a custom parser or report the issue.","cause":"This error means the parsed output from the device did not contain an expected key or structure defined in the Genie parser's schema for that specific command. This can happen due to variations in device OS versions, unexpected output, or bugs in the parser itself.","error":"genie.metaparser.util.exceptions.SchemaMissingKeyError: Show Command: show spanning-tree"},{"fix":"Use the full, precise command string as documented in the Genie Parsers list. Avoid common CLI shorthands if they are not explicitly handled by the Genie parser.","cause":"Genie's parsing mechanism could not find a matching parser for the provided command string or found multiple ambiguous matches. This is common with shorthand commands or commands not explicitly supported by a parser.","error":"Exception: Could not find parser for 'show interface status' or Search for 'show ip int br' is ambiguous."}]}