{"id":8901,"library":"clustershell","title":"ClusterShell","description":"ClusterShell is a Python library and set of tools designed for efficient command execution on Linux clusters. It provides robust NodeSet manipulation, parallel command execution, and a powerful CLI for High-Performance Computing (HPC) environments. The current version is 1.9.3, with releases typically occurring a few times a year, indicating active maintenance and development.","status":"active","version":"1.9.3","language":"en","source_language":"en","source_url":"https://github.com/clustershell/clustershell","tags":["cluster management","HPC","SSH","automation","nodeset"],"install":[{"cmd":"pip install clustershell","lang":"bash","label":"Basic installation"},{"cmd":"pip install 'clustershell[yaml]'","lang":"bash","label":"With YAML support (for configuration files)"}],"dependencies":[{"reason":"Required for parsing YAML configuration files if using advanced ClusterShell configuration.","package":"PyYAML","optional":true}],"imports":[{"note":"The top-level Python module is named 'ClusterShell' (uppercase C), not 'clustershell' (lowercase c), despite the PyPI package name.","wrong":"from clustershell.NodeSet import NodeSet","symbol":"NodeSet","correct":"from ClusterShell.NodeSet import NodeSet"},{"note":"The top-level Python module is named 'ClusterShell' (uppercase C), not 'clustershell' (lowercase c), despite the PyPI package name.","wrong":"from clustershell.Task import Task","symbol":"Task","correct":"from ClusterShell.Task import Task"}],"quickstart":{"code":"from ClusterShell.NodeSet import NodeSet\n\n# Create a NodeSet from a string representation\nnodes = NodeSet(\"node[0-3],host[10-12]\")\nprint(f\"Original NodeSet: {nodes}\")\n\n# Add individual nodes or other NodeSets\nnodes.add(\"server05\")\nprint(f\"After adding server05: {nodes}\")\n\n# Remove nodes\nnodes.remove(\"node1\")\nprint(f\"After removing node1: {nodes}\")\n\n# Check for membership\nprint(f\"Is node2 in the set? {'node2' in nodes}\")\n\n# Iterate over nodes\nprint(\"Nodes in the set:\")\nfor node in nodes:\n    print(f\"- {node}\")\n","lang":"python","description":"This quickstart demonstrates the core NodeSet functionality of ClusterShell, allowing you to parse, manipulate, and query groups of node names efficiently. This is a foundational step before performing distributed tasks."},"warnings":[{"fix":"Upgrade your environment to Python 3.6 or newer. Previous ClusterShell versions (1.7.x and below) are required for Python 2 compatibility.","message":"ClusterShell dropped support for Python 2.7.","severity":"breaking","affected_versions":">= 1.8.0"},{"fix":"Ensure you assign the result of these methods back to a variable, e.g., `nodes = nodes.intersection(other_nodes)`. Code expecting in-place modification will behave unexpectedly.","message":"NodeSet API changes: methods like `intersection()`, `difference()`, `union()`, and `symmetric_difference()` no longer modify NodeSets in-place but return a new NodeSet object.","severity":"breaking","affected_versions":">= 1.7.0"},{"fix":"To empty a NodeSet, re-initialize it: `nodes = NodeSet()`.","message":"The `NodeSet.clear()` method was deprecated.","severity":"deprecated","affected_versions":">= 1.7.0"},{"fix":"Before using `Task.run()`, ensure you can manually SSH to your target nodes. For debugging, use `task.set_info(\"ssh_options\", \"-vvv\")` to see detailed SSH output. For isolated testing, consider using `localhost` or mock objects.","message":"The `ClusterShell.Task` object's `run()` method performs actual SSH connections to specified nodes, which requires proper SSH setup (keys, agents, host reachability).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statements to use 'ClusterShell', e.g., `from ClusterShell.NodeSet import NodeSet`.","cause":"Attempting to import from the lowercase package name 'clustershell' instead of the module's actual name 'ClusterShell' (uppercase 'C').","error":"ImportError: No module named 'clustershell.NodeSet'"},{"fix":"Convert the NodeSet to a list first if you need indexed access: `node_list = list(nodes)`, then `node_list[0]`.","cause":"Attempting to access elements of a NodeSet using indexing (e.g., `nodes[0]`). NodeSets are iterable but not directly indexable like lists.","error":"TypeError: 'NodeSet' object is not subscriptable"},{"fix":"Verify SSH connectivity manually (e.g., `ssh user@node01 hostname`). Check SSH agent forwarding and host key configuration. For deeper diagnostics, enable verbose SSH output within ClusterShell: `task.set_info(\"ssh_options\", \"-vvv\")`.","cause":"Often due to underlying SSH connectivity issues (e.g., firewall, incorrect hostnames, lack of proper SSH key authentication, sshd not running on target), or issues with the command's execution path on the remote host.","error":"Command fails to execute on remote nodes during `Task.run()` without clear error message in stdout"}]}