{"id":5339,"library":"ncclient","title":"NETCONF Client for Python","description":"ncclient is a Python library that facilitates client-side scripting and application development around the NETCONF protocol. It aims to offer an intuitive API that maps XML-encoded NETCONF to Python constructs, making network-management scripts easier. The library is currently at version 0.7.1 and is actively maintained with releases happening periodically based on feature additions and bug fixes.","status":"active","version":"0.7.1","language":"en","source_language":"en","source_url":"https://github.com/ncclient/ncclient","tags":["networking","netconf","automation","ssh","network-management"],"install":[{"cmd":"pip install ncclient","lang":"bash","label":"Default installation with Paramiko"},{"cmd":"pip install ncclient[libssh]","lang":"bash","label":"Install with libssh transport (alternative to Paramiko)"}],"dependencies":[{"reason":"Default SSH transport for NETCONF session.","package":"paramiko","optional":false},{"reason":"XML parsing and manipulation.","package":"lxml","optional":false},{"reason":"Alternative SSH transport (requires 'libssh' system library).","package":"ssh-python","optional":true},{"reason":"Underlying library for XML processing (system dependency).","package":"libxml2","optional":false},{"reason":"Underlying library for XML processing (system dependency).","package":"libxslt","optional":false}],"imports":[{"symbol":"Manager","correct":"from ncclient import manager"},{"note":"While `connect_ssh` exists, the primary entry point is `manager.connect` which handles SSH by default and offers more flexibility with `device_params`.","wrong":"from ncclient.manager import connect_ssh","symbol":"connect","correct":"from ncclient import manager"}],"quickstart":{"code":"import os\nfrom ncclient import manager\nfrom ncclient.transport import SSHError\n\nHOST = os.environ.get('NETCONF_HOST', 'your_netconf_device_ip')\nPORT = int(os.environ.get('NETCONF_PORT', 830))\nUSER = os.environ.get('NETCONF_USER', 'admin')\nPASSWORD = os.environ.get('NETCONF_PASSWORD', 'password')\n\ndef get_device_capabilities():\n    try:\n        with manager.connect(host=HOST, port=PORT, \n                             username=USER, password=PASSWORD, \n                             hostkey_verify=False, \n                             device_params={'name': 'default'}) as m:\n            print(f\"Connected to {HOST} (Session ID: {m.session_id})\")\n            print(\"\\n--- Server Capabilities ---\")\n            for capability in m.server_capabilities:\n                print(f\"  - {capability}\")\n            print(\"\\n--- Get Running Configuration (filtered) ---\")\n            config_filter = '''\n                <filter type=\"subtree\">\n                    <system xmlns=\"urn:ietf:params:xml:ns:yang:ietf-system\"/>\n                </filter>\n            '''\n            result = m.get_config(source='running', filter=config_filter).data_xml\n            print(result)\n            m.close_session()\n    except SSHError as e:\n        print(f\"SSH Connection Error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    get_device_capabilities()","lang":"python","description":"This quickstart connects to a NETCONF-enabled device, retrieves its capabilities, and then fetches a filtered portion of the running configuration. It uses environment variables for connection details for security and flexibility. The `hostkey_verify=False` is used here for simplicity, but should be replaced with proper host key verification in production environments."},"warnings":[{"fix":"Review `manager.connect` parameters and test connectivity thoroughly after upgrading. If encountering issues, ensure parameters are compatible with the chosen transport (`Paramiko` or `ssh-python`).","message":"Version 0.7.0 introduced `ssh-python` as an optional SSH transport, which means the `manager.connect` call is NOT 100% backwards compatible with all possible parameters that may have been passed when only `Paramiko` was used. Code relying on specific `Paramiko` nuances might break.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Upgrade Python to 3.7 or newer. The library's `requires_python` is `>=3.7`.","message":"Support for Python 2 was officially removed in version 0.6.17. Users on Python 2.x will encounter errors and should upgrade their Python environment.","severity":"breaking","affected_versions":">=0.6.17"},{"fix":"Decide which SSH transport is preferred. If `ssh-python` is desired, install with `pip install ncclient[libssh]` and ensure `libssh` is installed on the system. Otherwise, `pip install ncclient` will use Paramiko.","message":"By default, `ncclient` uses Paramiko for its SSH transport. As of v0.7.0, an alternative `ssh-python` transport can be used by installing `ncclient[libssh]`. This choice can affect behavior and dependency requirements, as `ssh-python` typically depends on the system's `libssh` library.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Implement proper host key verification in production. This usually involves setting `hostkey_verify=True` and managing `known_hosts` files or providing host keys explicitly.","message":"Using `hostkey_verify=False` in `manager.connect` disables SSH host key checking, which is insecure and not recommended for production environments. This is often seen in examples for simplicity.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review asynchronous code, especially if migrating from older versions. Check official documentation or examples for the correct `async_mode` usage with recent Python versions.","message":"The `async_mode` attribute, which was previously a direct attribute of the `Manager` instance for asynchronous RPC requests, had changes in its implementation/usage around version 0.6.0 for compatibility with Python 3.7+.","severity":"gotcha","affected_versions":">=0.6.0"},{"fix":"Always specify the correct `device_params` name for the target device vendor (e.g., `{'name': 'junos'}` for Juniper, `{'name': 'nexus'}` for Cisco Nexus, `{'name': 'huawei'}` for Huawei). Refer to documentation for a full list of supported handlers.","message":"For vendor-specific NETCONF operations and capabilities, `ncclient` relies on device handlers specified via `device_params={'name': '<vendor_alias>'}`. Failing to set this correctly for a specific device type (e.g., 'junos', 'nexus') might lead to unexpected behavior or missing functionality.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}