{"id":7834,"library":"unicon","title":"Unicon Connection Library","description":"Unicon is a Python package that provides a unified connection experience to network devices via typical command-line management interfaces (CLI). It serves as the standard CLI connection implementation within the Cisco pyATS framework, offering direct and proxied connections, expect-like programming, and multi-vendor support through an agnostic API. Initially developed internally by Cisco, it was released publicly in late 2017 through Cisco DevNet. [1, 2, 12] The current version is 26.3, released on April 2, 2026, and the project maintains an active release cadence, often aligned with the broader pyATS/Genie framework releases. [2, 23]","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/unicon.plugins","tags":["networking","device management","network automation","cli","cisco","pyats"],"install":[{"cmd":"pip install unicon","lang":"bash","label":"Install Unicon"}],"dependencies":[{"reason":"Used for parsing YAML configurations, common in pyATS testbeds.","package":"pyyaml","optional":false},{"reason":"Likely used for formatting output in a tabular manner.","package":"PrettyTable","optional":false},{"reason":"Required for secure communication protocols like SSH.","package":"cryptography","optional":false}],"imports":[{"note":"The primary class for establishing and managing device connections.","symbol":"Connection","correct":"from unicon.core.connection import Connection"}],"quickstart":{"code":"import os\nfrom unicon.core.connection import Connection\n\n# Replace with your device details and credentials\ndevice_settings = {\n    'hostname': os.environ.get('DEVICE_HOSTNAME', '10.0.0.1'),\n    'os': os.environ.get('DEVICE_OS', 'ios'), # e.g., ios, nxos, iosxe\n    'type': os.environ.get('DEVICE_TYPE', 'router'),\n    'username': os.environ.get('DEVICE_USERNAME', 'admin'),\n    'password': os.environ.get('DEVICE_PASSWORD', 'Cisco123'),\n    'enable_password': os.environ.get('DEVICE_ENABLE_PASSWORD', 'Cisco123'),\n}\n\ntry:\n    # Create a connection instance\n    conn = Connection(hostname=device_settings['hostname'],\n                      os=device_settings['os'],\n                      type=device_settings['type'],\n                      start_state='exec') # Specify the initial state to reach\n\n    # Provide credentials (Unicon can also retrieve from testbed YAML)\n    conn.settings.CLI_USERNAME = device_settings['username']\n    conn.settings.CLI_PASSWORD = device_settings['password']\n    conn.settings.CLI_ENABLE_PASSWORD = device_settings['enable_password']\n\n    # Connect to the device\n    print(f\"Connecting to {device_settings['hostname']}...\")\n    conn.connect()\n    print(\"Connection successful.\")\n\n    # Execute a command\n    output = conn.execute('show version')\n    print(\"\\n--- show version output ---\")\n    print(output)\n\n    # Disconnect from the device\n    conn.disconnect()\n    print(\"Disconnected.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to establish a basic CLI connection to a network device using Unicon, execute a command, and then disconnect. It uses environment variables for sensitive credentials for security and easy testing. [12]"},"warnings":[{"fix":"Ensure your Python environment is 3.8 or higher. Upgrade Python or activate a compatible virtual environment. [2]","message":"Unicon's Python compatibility officially requires Python 3.8 or newer. Using older Python versions will lead to installation failures or runtime errors.","severity":"breaking","affected_versions":"< 26.0"},{"fix":"Install `unicon.plugins` (`pip install unicon.plugins`). Refer to Cisco DevNet documentation for supported platforms and necessary plugins for your specific device. [1, 12]","message":"Unicon relies heavily on plugins for specific device platforms and OS capabilities. If you encounter issues connecting to a device or executing specific commands, ensure you have the correct `unicon.plugins` package installed and that it supports your target device/OS combination.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Start with common error patterns (e.g., `^%Error`, `^% Invalid`, `Timeout`). Test against various error conditions on your target devices. Use regular expressions carefully and consider broad patterns like `%.*?%` for general error messages, then refine to avoid false positives. Consult device documentation for expected error messages. [24]","message":"When using `conn.execute()` with `reply` or `error_pattern` arguments, comprehensively listing all possible CLI error patterns or prompts for a given command can be challenging due to vendor/OS variations. Incomplete patterns may lead to command failures or timeouts.","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":"Run `pip install unicon` to install the library. If using a virtual environment, ensure it is activated before installation and execution. [18, 19]","cause":"The 'unicon' package is not installed in the current Python environment or the environment is not activated.","error":"ModuleNotFoundError: No module named 'unicon'"},{"fix":"Double-check `CLI_USERNAME`, `CLI_PASSWORD`, and `CLI_ENABLE_PASSWORD` (if applicable) in your code or testbed YAML. Verify network connectivity and device accessibility. Ensure the user has appropriate permissions on the device. [12]","cause":"Incorrect username, password, or enable password provided, or the device rejected the credentials.","error":"unicon.core.exceptions.ConnectionError: Failed to connect to device ... Authentication Failed"},{"fix":"Increase the `timeout` parameter in your `Connection` object or `execute()` call. Verify network latency and device responsiveness. Ensure the `start_state` is correct for the device's initial prompt. [12]","cause":"The device did not respond within the expected timeout period during connection, state transition (e.g., to enable mode), or command execution.","error":"unicon.core.exceptions.TimeoutError: Connection timed out while trying to reach state 'enable'"}]}