Skip to main content

Pure python SSH tunnels

Project description

CircleCI coveralls

DwnMonth DwnWeek DwnDay

WORKS WITH: python 2.6, python 2.7, python 3.2, python 3.3, python 3.4, python 3.5

Author: Pahaz Blinov


Inspired by but it doesn’t work on Windows.

See also:



pip install sshtunnel


easy_install sshtunnel

Install from source:

python develop

Testing the package

pip install -r requirements-test.txt
python test

Usage examples: SSH tunnel to remote server

Useful when you need to connect to a local port on remote server through ssh tunnel. It works by opening a port forwarding ssh connection in the background, using threads. The connection(s) are closed when explicitly calling the close method of the returned SSHTunnelForwarder object.:


-------------+              |    +----------+               +---------
    LOCAL    |              |    |  REMOTE  |               | PRIVATE
    CLIENT   | <== SSH ========> |  SERVER  | <== local ==> | SERVER
-------------+              |    +----------+               +---------


Fig1: How to connect to PRIVATE SERVER through SSH tunnel.

Example 1

from sshtunnel import SSHTunnelForwarder

server = SSHTunnelForwarder(
    ('', 22),
    remote_bind_address=('', 5555)


# work with `SECRET SERVICE` through `server.local_bind_port`.


Example 2

Example of a port forwarding for the Vagrant MySQL local port:

from sshtunnel import SSHTunnelForwarder
from time import sleep

with SSHTunnelForwarder(
    ('localhost', 2222),
    remote_bind_address=('', 3306)
) as server:

    while True:
        # press Ctrl-C for stopping


Or simply using the CLI:

python -m sshtunnel -U vagrant -P vagrant -L :3306 -R -p 2222 localhost


SSHTunnelForwarder arguments

This is an incomplete list of arguments. See __init__() method of SSHTunnelForwarder class in for a full list.

ssh_proxy = None

Accepts a paramiko.ProxyCommand object where all SSH traffic will be passed through. See either the paramiko.ProxyCommand documentation or ProxyCommand in ssh_config(5) for more information.

Note: ssh_proxy overrides any ProxyCommand sourced from the user ssh_config.

Note: ssh_proxy is ignored if ssh_proxy_enabled != True.

ssh_proxy_enabled = True

If True (default) and user’s ssh_config file contains a ProxyCommand directive that matches the specified ssh_address_or_host (or first positional argument), SSHTunnelForwarder will create a paramiko.ProxyCommand object where all SSH traffic will be passed through.

See the ssh_proxy argument for more details.


  • v.0.0.7
    • Tunnels can now be stopped and started safely (#41)
    • Add timeout to SSH gateway and keep-alive messages (#29)
    • Allow sending a pkey directly (#43)
    • Add -V CLI option to show current version
    • Refactoring
  • v.0.0.6
    • add -S CLI options for ssh private key password support (pahaz)
  • v.0.0.5
    • add ssh_proxy argument, as well as ssh_config(5) ProxyCommand support (lewisthompson)
    • add some python 2.6 compatibility fixes (mrts)
    • paramiko.transport inherits handlers of loggers passed to SSHTunnelForwarder (fernandezcuesta)
    • fix #34, #33, code style and docs (fernandezcuesta)
    • add tests (pahaz)
    • add CI integration (pahaz)
    • normal packaging (pahaz)
    • disable check distenation socket connection by SSHTunnelForwarder.local_is_up (pahaz) [changed default behavior]
    • use daemon mode = False in all threads by default; detail (pahaz) [changed default behavior]
  • v.
    • fix issue #24 - hide ssh password in logs (pahaz)
  • v.
    • fix default port issue #19 (pahaz)
  • v.
    • fix Thread.daemon mode for Python < 3.3 #16, #21 (lewisthompson, ewrogers)
  • v.
    • fix CLI issues #13 (pahaz)
  • v.0.0.4
    • daemon mode by default for all threads (fernandezcuesta, pahaz) - incompatible
    • move make_ssh_forward_server to SSHTunnelForwarder.make_ssh_forward_server (pahaz, fernandezcuesta) - incompatible
    • move make_ssh_forward_handler to SSHTunnelForwarder.make_ssh_forward_handler_class (pahaz, fernandezcuesta) - incompatible
    • rename open to open_tunnel (fernandezcuesta) - incompatible
    • add CLI interface (fernandezcuesta)
    • support opening several tunnels at once (fernandezcuesta)
    • improve stability and readability (fernandezcuesta, pahaz)
    • improve logging (fernandezcuesta, pahaz)
    • add raise_exception_if_any_forwarder_have_a_problem argument for opening several tunnels at once (pahaz)
    • add ssh_config_file argument support (fernandezcuesta)
    • add Python 3 support (fernandezcuesta, pahaz)
  • v.0.0.3
    • add threaded options (cameronmaske)
    • fix exception error message, correctly printing destination address (gdmachado)
    • fix pip install fails (cjermain, pahaz)
  • v.0.0.1
    • SSHTunnelForwarder class (pahaz)
    • open function (pahaz)


usage: sshtunnel    [-h] [-U SSH_USERNAME] [-p SSH_PORT] [-P SSH_PASSWORD] -R
                    IP:PORT [IP:PORT ...] [-L [IP:PORT [IP:PORT ...]]]
                    [-k SSH_HOST_KEY] [-K RSA_KEY_FILE]
                    [-S RSA_KEY_FILE_PASSWORD] [-t] [-v]

Pure python ssh tunnel utils

positional arguments:
  ssh_address           SSH server IP address (GW for ssh tunnels)
                        set with "-- ssh_address" if immediately after -R or -L

optional arguments:
  -h, --help            show this help message and exit
                        SSH server account username
  -p SSH_PORT, --server_port SSH_PORT
                        SSH server TCP port (default: 22)
                        SSH server account password
  -R IP:PORT [IP:PORT ...], --remote_bind_address IP:PORT [IP:PORT ...]
                        Remote bind address sequence: ip_1:port_1 ip_2:port_2 ... ip_n:port_n
                        Equivalent to ssh -Lxxxx:IP_ADDRESS:PORT
                        If omitted, default port is 22.
                        Example: -R
  -L [IP:PORT [IP:PORT ...]], --local_bind_address [IP:PORT [IP:PORT ...]]
                        Local bind address sequence: ip_1:port_1 ip_2:port_2 ... ip_n:port_n
                        Equivalent to ssh -LPORT:xxxxxxxxx:xxxx, being the local IP address optional.
                        By default it will listen in all interfaces ( and choose a random port.
                        Example: -L :40000
  -k SSH_HOST_KEY, --ssh_host_key SSH_HOST_KEY
                        Gateway's host key
  -K RSA_KEY_FILE, --private_key_file RSA_KEY_FILE
                        RSA private key file
  -S RSA_KEY_FILE_PASSWORD, --private_key_file_password RSA_KEY_FILE_PASSWORD
                        RSA private key file password
  -t, --threaded        Allow concurrent connections to each tunnel
  -v, --verbosity       Increase output verbosity (default: 40)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sshtunnel, version 0.0.7
Filename, size File type Python version Upload date Hashes
Filename, size sshtunnel-0.0.7.tar.gz (20.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page