ssh-python Single Host Client

Single host non-blocking client based on ssh-python (libssh). Suitable for running asynchronous commands on a single host.

class pssh.clients.ssh.single.SSHClient(host, user=None, password=None, port=None, pkey=None, cert_file=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, identity_auth=True, gssapi_auth=False, gssapi_server_identity=None, gssapi_client_identity=None, gssapi_delegate_credentials=False, _auth_thread_pool=True)

ssh-python based non-blocking client.

  • host (str) – Host name or IP to connect to.

  • user (str) – User to connect as. Defaults to logged in user.

  • password (str) – Password to use for password authentication.

  • port (int) – SSH port to connect to. Defaults to SSH default (22)

  • pkey (str) – Private key file path to use for authentication. Path must be either absolute path or relative to user home directory like ~/<path>.

  • cert_file (str) – Public key signed certificate file to use for authentication. The corresponding private key must also be provided via pkey parameter. For example pkey='id_rsa',cert_file='' for RSA signed certificate. Path must be absolute or relative to user home directory.

  • num_retries (int) – (Optional) Number of connection and authentication attempts before the client gives up. Defaults to 3.

  • retry_delay (int) – Number of seconds to wait between retries. Defaults to pssh.constants.RETRY_DELAY

  • timeout (int) – (Optional) If provided, all commands will timeout after <timeout> number of seconds.

  • allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent. Currently unused.

  • identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base_ssh_client.BaseSSHClient.IDENTITIES

  • gssapi_server_identity (str) – Enable GSS-API authentication. Uses GSS-MIC key exchange. Enabled if either gssapi_server_identity or gssapi_client_identity are provided.

  • gssapi_server_identity – Set GSSAPI server identity.

  • gssapi_client_identity (str) – Set GSSAPI client identity.

  • gssapi_delegate_credentials (bool) – Enable/disable server credentials delegation.


pssh.exceptions.PKeyFileError on errors finding provided private key.


Close channel.


channel ( – The channel to close.


Close socket if needed.

execute(cmd, use_pty=False, channel=None)

Execute command on remote host.

  • cmd (str) – The command string to execute.

  • use_pty (bool) – Whether or not to request a PTY on the channel executing command.

  • channel ( – Channel to use. New channel is created if not provided.


Checks if remote command has finished - has server sent client EOF.

Return type



Get exit status code for channel or None if not ready.


channel ( – The channel to get status from.

Return type

int or None


Open new channel from session.


ssh-python based co-operative gevent poll on session socket.

wait_finished(host_output, timeout=None)

Wait for EOF from channel and close channel.

Used to wait for remote command completion and be able to gather exit code.

  • host_output (pssh.output.HostOutput) – Host output of command to wait for.

  • timeout (float) – Timeout value in seconds - defaults to no timeout.


pssh.exceptions.Timeout after <timeout> seconds if timeout set.