ClusterShell

1.9.3 · active · verified Thu Apr 16

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.

Common errors

```
ImportError: No module named 'clustershell.NodeSet'
```
cause Attempting to import from the lowercase package name 'clustershell' instead of the module's actual name 'ClusterShell' (uppercase 'C').

fix Change your import statements to use 'ClusterShell', e.g., `from ClusterShell.NodeSet import NodeSet`.
```
TypeError: 'NodeSet' object is not subscriptable
```
cause Attempting to access elements of a NodeSet using indexing (e.g., `nodes[0]`). NodeSets are iterable but not directly indexable like lists.

fix Convert the NodeSet to a list first if you need indexed access: `node_list = list(nodes)`, then `node_list[0]`.
```
Command fails to execute on remote nodes during `Task.run()` without clear error message in stdout
```
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.

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

Warnings

breaking ClusterShell dropped support for Python 2.7.
Fix: Upgrade your environment to Python 3.6 or newer. Previous ClusterShell versions (1.7.x and below) are required for Python 2 compatibility.
breaking NodeSet API changes: methods like `intersection()`, `difference()`, `union()`, and `symmetric_difference()` no longer modify NodeSets in-place but return a new NodeSet object.
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.
deprecated The `NodeSet.clear()` method was deprecated.
Fix: To empty a NodeSet, re-initialize it: `nodes = NodeSet()`.
gotcha The `ClusterShell.Task` object's `run()` method performs actual SSH connections to specified nodes, which requires proper SSH setup (keys, agents, host reachability).
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.

Install

pip install clustershell Basic installation
pip install 'clustershell[yaml]' With YAML support (for configuration files)

Imports

NodeSet
wrong:
```
from clustershell.NodeSet import NodeSet
```
correct:
```
from ClusterShell.NodeSet import NodeSet
```
The top-level Python module is named 'ClusterShell' (uppercase C), not 'clustershell' (lowercase c), despite the PyPI package name.
Task
wrong:
```
from clustershell.Task import Task
```
correct:
```
from ClusterShell.Task import Task
```
The top-level Python module is named 'ClusterShell' (uppercase C), not 'clustershell' (lowercase c), despite the PyPI package name.

Quickstart

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.

from ClusterShell.NodeSet import NodeSet

# Create a NodeSet from a string representation
nodes = NodeSet("node[0-3],host[10-12]")
print(f"Original NodeSet: {nodes}")

# Add individual nodes or other NodeSets
nodes.add("server05")
print(f"After adding server05: {nodes}")

# Remove nodes
nodes.remove("node1")
print(f"After removing node1: {nodes}")

# Check for membership
print(f"Is node2 in the set? {'node2' in nodes}")

# Iterate over nodes
print("Nodes in the set:")
for node in nodes:
    print(f"- {node}")

view raw JSON →