ncclient

library0.7.1pypypi✓ verified 21d ago

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.

http-networking devops serialization

pip install ncclient

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · NCCLIENT

ncclient

http-networkingpythonv0.7.1

Install

3.6s avg

Import

191ms

Disk

64MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

1/2 runs

✓ 4s

py 3.11

1/2 runs

✓ 3.4s

py 3.12

1/2 runs

✓ 2.9s

py 3.13

1/2 runs

✓ 3.1s

py 3.9

1/2 runs

✓ 4.8s

64MB installed

● package 64MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Manager

✓ from ncclient import manager

connect

✓ from ncclient import manager

✗ from ncclient.manager import connect_ssh

While `connect_ssh` exists, the primary entry point is `manager.connect` which handles SSH by default and offers more flexibility with `device_params`.

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.

import os from ncclient import manager from ncclient.transport import SSHError HOST = os.environ.get('NETCONF_HOST', 'your_netconf_device_ip') PORT = int(os.environ.get('NETCONF_PORT', 830)) USER = os.environ.get('NETCONF_USER', 'admin') PASSWORD = os.environ.get('NETCONF_PASSWORD', 'password') def get_device_capabilities(): try: with manager.connect(host=HOST, port=PORT, username=USER, password=PASSWORD, hostkey_verify=False, device_params={'name': 'default'}) as m: print(f"Connected to {HOST} (Session ID: {m.session_id})") print("\n--- Server Capabilities ---") for capability in m.server_capabilities: print(f" - {capability}") print("\n--- Get Running Configuration (filtered) ---") config_filter = ''' <filter type="subtree"> <system xmlns="urn:ietf:params:xml:ns:yang:ietf-system"/> </filter> ''' result = m.get_config(source='running', filter=config_filter).data_xml print(result) m.close_session() except SSHError as e: print(f"SSH Connection Error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") if __name__ == '__main__': get_device_capabilities()

Debug

Known issues

breakingVersion 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.

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`).

affects: >=0.7.0

breakingSupport 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.

fix

Upgrade Python to 3.7 or newer. The library's `requires_python` is `>=3.7`.

affects: >=0.6.17

gotchaBy 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.

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.

affects: >=0.7.0

gotchaUsing `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.

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.

affects: All versions

gotchaThe `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+.

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.

affects: >=0.6.0

gotchaFor 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.

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.

affects: All versions

Errors

Common errors & fixes

ncclient.transport.errors.SSHError: Negotiation failed: Error reading

This error often occurs when the remote NETCONF device closes the SSH connection unexpectedly during negotiation, possibly due to rate-limiting on the device or an unresponsive server.

fix

Introduce a `time.sleep()` delay before `manager.connect()` calls if making rapid, successive connections. Verify the remote NETCONF server is not overloaded or configured with strict rate limits. Ensure SSH parameters are compatible.

RPCError: Missing element in the specified context - target datastore missing

The XML payload sent in a NETCONF RPC (e.g., `copy-config`, `edit-config`) is missing a required element, such as the `target` or `source` datastore, or another essential tag as defined by the YANG model on the device. This can also manifest as an `<error-tag>missing-element</error-tag>` or `bad-element` in the RPC reply.

fix

Carefully review the XML payload against the device's YANG models and NETCONF capabilities to ensure all mandatory elements, especially `target` and `source` in `copy-config` or `edit-config`, are correctly included and formatted according to the device's expectations.

ERROR: Missing element's "namespace". (/nc:rpc/nc:edit-config/config)

The XML payload contains an element (like `<config>`) that is missing its required XML namespace declaration or is using an incorrect namespace prefix for a standard NETCONF operation.

fix

Ensure all NETCONF-specific elements (e.g., `<rpc>`, `<edit-config>`, `<config>`) are properly prefixed with `nc:` and that the `nc` prefix is bound to the correct NETCONF namespace `xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"` in the root `<rpc>` tag.

Intermittent "Capability exchange timed out"

The NETCONF client failed to receive the server's `<hello>` message or complete the capability exchange within the allotted timeout period. This can be due to network latency, an unresponsive server, or firewall issues blocking the exchange.

fix

Increase the `timeout` parameter during the `manager.connect()` call to allow more time for the capability exchange. Verify network connectivity to the NETCONF server and ensure the server is running and responsive.

Upgrade

Version history

0.7.1latest on PyPI · released Mar 15, 2026

Audit

Dependencies

paramikorequiredDefault SSH transport for NETCONF session.

lxmlrequiredXML parsing and manipulation.

ssh-pythonoptionalAlternative SSH transport (requires 'libssh' system library).

libxml2requiredUnderlying library for XML processing (system dependency).

libxsltrequiredUnderlying library for XML processing (system dependency).

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/ncclient/ncclient ↗

packagehttps://pypi.org/project/ncclient/ ↗

homepagehttps://ncclient.readthedocs.io ↗

docshttps://ncclient.readthedocs.io/ ↗