Unicon Connection Library

26.3 · active · verified Thu Apr 16

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]

Common errors

```
ModuleNotFoundError: No module named 'unicon'
```
cause The 'unicon' package is not installed in the current Python environment or the environment is not activated.

fix Run `pip install unicon` to install the library. If using a virtual environment, ensure it is activated before installation and execution. [18, 19]
```
unicon.core.exceptions.ConnectionError: Failed to connect to device ... Authentication Failed
```
cause Incorrect username, password, or enable password provided, or the device rejected the credentials.

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]
```
unicon.core.exceptions.TimeoutError: Connection timed out while trying to reach state 'enable'
```
cause The device did not respond within the expected timeout period during connection, state transition (e.g., to enable mode), or command execution.

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]

Warnings

breaking Unicon's Python compatibility officially requires Python 3.8 or newer. Using older Python versions will lead to installation failures or runtime errors.
Fix: Ensure your Python environment is 3.8 or higher. Upgrade Python or activate a compatible virtual environment. [2]
gotcha 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.
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]
gotcha 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.
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]

Install

pip install unicon Install Unicon

Imports

Connection
```
from unicon.core.connection import Connection
```
The primary class for establishing and managing device connections.

Quickstart

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]

import os
from unicon.core.connection import Connection

# Replace with your device details and credentials
device_settings = {
    'hostname': os.environ.get('DEVICE_HOSTNAME', '10.0.0.1'),
    'os': os.environ.get('DEVICE_OS', 'ios'), # e.g., ios, nxos, iosxe
    'type': os.environ.get('DEVICE_TYPE', 'router'),
    'username': os.environ.get('DEVICE_USERNAME', 'admin'),
    'password': os.environ.get('DEVICE_PASSWORD', 'Cisco123'),
    'enable_password': os.environ.get('DEVICE_ENABLE_PASSWORD', 'Cisco123'),
}

try:
    # Create a connection instance
    conn = Connection(hostname=device_settings['hostname'],
                      os=device_settings['os'],
                      type=device_settings['type'],
                      start_state='exec') # Specify the initial state to reach

    # Provide credentials (Unicon can also retrieve from testbed YAML)
    conn.settings.CLI_USERNAME = device_settings['username']
    conn.settings.CLI_PASSWORD = device_settings['password']
    conn.settings.CLI_ENABLE_PASSWORD = device_settings['enable_password']

    # Connect to the device
    print(f"Connecting to {device_settings['hostname']}...")
    conn.connect()
    print("Connection successful.")

    # Execute a command
    output = conn.execute('show version')
    print("\n--- show version output ---")
    print(output)

    # Disconnect from the device
    conn.disconnect()
    print("Disconnected.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →