{"id":8189,"library":"genie-libs-clean","title":"Genie Libs Clean","description":"Genie Libs Clean (version 26.3) is a component of the CiscoTestAutomation's Genie framework, providing functionalities for cleaning network devices. It automates tasks such as removing configurations, upgrading/downgrading OS, and reloading devices to prepare them for new test runs or restore them to a known state. It is actively maintained as part of the broader Genie/pyATS ecosystem, with a release cadence tied to the pyATS framework.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/genie.libs.clean","tags":["networking","devops","automation","cisco","pyats","genie","device-management","testing"],"install":[{"cmd":"pip install genie-libs-clean","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core automation framework on which Genie and its libraries are built.","package":"pyats","optional":false},{"reason":"The main Genie framework, required for core Genie functionalities.","package":"genie","optional":false}],"imports":[{"note":"The `Clean` class resides in the `clean.py` submodule, not directly under `genie.libs.clean`.","wrong":"from genie.libs.clean import Clean","symbol":"Clean","correct":"from genie.libs.clean.clean import Clean"}],"quickstart":{"code":"import os\nimport yaml\nfrom pyats.topology import Device\nfrom genie.libs.clean.clean import Clean\n\n# --- This example uses a mock device for demonstration ---\n# In a real scenario, `device` would come from a pyATS testbed file\n# and `device.connect()` would establish a connection.\n\ndevice = Device(name=\"dut1\", os=\"iosxe\", connections={'cli': {'protocol': 'ssh'}})\nprint(f\"Created mock device: {device.name}\")\n\n# Define a simple clean YAML process. In a real test, this\n# would often be loaded from a file or generated dynamically.\nclean_yaml_process = \"\"\"\nclean:\n    order:\n        - stage: clear_logging\n        - stage: reload\n\"\"\"\n\n# Instantiate the Clean object with the device and the clean definition\ntry:\n    clean_obj = Clean(device=device, clean_info=yaml.safe_load(clean_yaml_process))\n    print(\"Clean object instantiated successfully.\")\n\n    # Execute the clean process.\n    # IMPORTANT: clean_obj.go() would execute actual commands on the device.\n    # For this quickstart, we are simulating its call.\n    # To run for real, ensure device is connected and testbed setup correctly.\n    print(\"Simulating clean process execution (clean_obj.go() is commented out).\")\n    # clean_obj.go()\n\n    print(\"Quickstart demonstration completed.\")\n\nexcept Exception as e:\n    print(f\"An error occurred during quickstart: {e}\")\n    print(\"Ensure all dependencies (pyATS, genie) are installed and versions are compatible.\")\n","lang":"python","description":"This quickstart demonstrates how to instantiate and prepare a `Clean` object with a device and a basic clean YAML process. It shows the correct import and initialization. Note that `clean_obj.go()` is commented out to prevent actual device interaction in a basic runnable example; in a real environment, it would execute the defined clean stages on the device."},"warnings":[{"fix":"Always install `pyats` and `genie` packages from the same release train (e.g., `pip install pyats==<X> genie==<X> genie.libs.clean==<X>`). Refer to Cisco's official pyATS/Genie documentation for version compatibility matrices.","message":"Version compatibility between `pyATS`, `genie`, and `genie-libs-clean` is critical. Mismatched major versions can lead to `ImportError`s, `AttributeError`s, or unexpected behavior.","severity":"breaking","affected_versions":"All versions"},{"fix":"Thoroughly review your pyATS testbed file, ensure the device OS is correctly specified, and verify that the required Genie parsers and device-specific functionalities are available for your device and OS version. Check detailed logs for underlying errors during clean execution.","message":"The `Clean` process relies heavily on specific device configurations, parsers, and operating system support within the pyATS testbed and Genie libraries. Misconfigured devices, unsupported OS versions, or missing custom parsers will lead to clean stage failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always validate your clean YAML against the expected schema provided in the Genie documentation. Pay close attention to stage names (e.g., `install_os`, `apply_configuration`, `reload`) and their required arguments.","message":"The `clean_info` YAML structure is highly schema-driven. Incorrect indentation, misspelled stage names, or invalid arguments within the YAML definition will cause the `Clean` object to fail during initialization or execution.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the import statement to `from genie.libs.clean.clean import Clean`.","cause":"The `Clean` class is located in a submodule `clean.py`, not directly under `genie.libs.clean`.","error":"ImportError: cannot import name 'Clean' from 'genie.libs.clean'"},{"fix":"Review your `clean_info` YAML. The top-level key should typically be `clean`, and its value should be a dictionary defining the clean process. Ensure correct YAML syntax and indentation.","cause":"The YAML structure provided to the `Clean` object (via `clean_info`) is incorrect or malformed, often due to improper indentation or invalid top-level keys.","error":"pyats.exceptions.SchemaError: Key 'clean' must be of type 'dict'"},{"fix":"Inspect the pyATS run logs for detailed output from the failing stage. This often reveals the exact command that failed, network errors, or device-specific error messages. Verify device connectivity and the validity of the clean stage for the target device.","cause":"A specific stage in the clean process failed, often due to underlying device connectivity issues, incorrect commands executed by Genie, or unexpected device state.","error":"Error: 'reload' stage failed for device dut1"}]}