Super fast SSH2 protocol library. ssh2-python provides Python bindings for libssh2.

Binary wheel packages are provided for Linux, OSX and Windows, all Python versions, with libssh2 and its required libraries included.

Wheel packages have no dependencies.

pip may need to be updated to be able to install binary wheel packages - pip install -U pip.

pip install ssh2-python

System packages are also available on the latest release page built on Centos/RedHat 6/7, Ubuntu 14.04/16.04, Debian 7/8 and Fedora 22/23/24.

System packages have no dependencies other than the libssh2 system library.

Conda is another installation option - see documentation for more detailed instructions.

Currently the vast majority of the libssh2 API has been implemented with only few exceptions.

Complete example scripts for various operations can be found in the examples directory.

In addition, as ssh2-python is a thin wrapper of libssh2 with Python semantics, its code examples can be ported straight over to Python with only minimal changes.

The library uses Cython based native code extensions as wrappers to libssh2.

Extension features:

• Thread safe - GIL is released as much as possible
• Very low overhead
• Super fast as a consequence of the excellent C library it uses and prodigious use of native code
• Object oriented - memory freed automatically and safely as objects are garbage collected by Python
• Use Python semantics where applicable, such as context manager and iterator support for opening and reading from SFTP file handles
• Expose errors as Python exceptions where possible
• Provide access to libssh2 error code definitions

Both byte and unicode strings are accepted as arguments and encoded appropriately. To change default encoding, utf-8, change the value of ssh2.utils.ENCODING. Channel output is always byte strings.

See Complete Example for a complete example including socket connect.

Please use either the issue tracker for reporting issues with code or the mail group for discussion and questions.

Contributions are most welcome!

Connect and get available authentication methods.

from __future__ import print_function

from ssh2.session import Session

sock = <create and connect socket>

session = Session()
session.handshake(sock)
print(session.userauth_list())

['publickey', 'password', 'keyboard-interactive']

session.agent_auth(user)

channel = session.open_session()
channel.execute('echo Hello')

size, data = channel.read()
while(size > 0):
    print(data)
    size, data = channel.read()

Hello

print("Exit status: %s" % (channel.get_exit_status()))

Exit status: 0

session.userauth_publickey_fromfile(
    username, 'my_pkey.pub', 'my_pkey', '')

Where '' can be a passphrase.

session.userauth_password(
    username, '<my password>')

sftp = session.sftp_init()
with sftp.open(<remote file to read>, 0, 0) as remote_fh, \
        open(<file to write>, 'wb') as local_fh:
    for size, data in remote_fh:
        local_fh.write(data)

A simple usage example looks very similar to libssh2 usage examples.

See examples directory for more complete example scripts.

As mentioned, ssh2-python is intentially a thin wrapper over libssh2 and directly maps most of its API.

Clients using this library can be much simpler to use than interfacing with the libssh2 API directly.

from __future__ import print_function

import os
import socket

from ssh2.session import Session

host = 'localhost'
user = os.getlogin()

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((host, 22))

session = Session()
session.handshake(sock)
session.agent_auth(user)

channel = session.open_session()
channel.execute('echo me; exit 2')
size, data = channel.read()
while size > 0:
    print(data)
    size, data = channel.read()
channel.close()
print("Exit status: %s" % channel.get_exit_status())

• SSH channel operations (exec,shell,subsystem) and methods
• SSH agent functionality
• Public key authentication and management
• SFTP operations
• SFTP file handles and attributes
• SSH port forwarding and tunnelling
• Non-blocking mode
• SCP send and receive
• Listener for port forwarding
• Subsystem support

And more, as per libssh2 functionality.

Performance of above example, compared with Paramiko.

time python examples/example_echo.py
time python examples/paramiko_comparison.py

real       0m0.141s
user       0m0.037s
sys        0m0.008s

real       0m0.592s
user       0m0.351s
sys        0m0.021s