Skip to main content

Pure python SSH tunnels

Project description

CircleCI AppVeyor Documentation Status coveralls version

pyversions license

Author: Pahaz


Inspired by, which doesn’t work on Windows.

See also:



sshtunnel is on PyPI, so simply run:

pip install sshtunnel


easy_install sshtunnel


conda install -c conda-forge sshtunnel

to have it installed in your environment.

For installing from source, clone the repo and run:

python install

Testing the package

In order to run the tests you first need tox and run:

python test

Usage scenarios

One of the typical scenarios where sshtunnel is helpful is depicted in the figure below. User may need to connect a port of a remote server (i.e. 8080) where only SSH port (usually port 22) is reachable.


-------------+              |    +----------+
    LOCAL    |              |    |  REMOTE  | :22 SSH
    CLIENT   | <== SSH ========> |  SERVER  | :8080 web service
-------------+              |    +----------+
                         FIREWALL (only port 22 is open)


Fig1: How to connect to a service blocked by a firewall through SSH tunnel.

If allowed by the SSH server, it is also possible to reach a private server (from the perspective of REMOTE SERVER) not directly visible from the outside (LOCAL CLIENT’s perspective).


-------------+              |    +----------+               +---------
    LOCAL    |              |    |  REMOTE  |               | PRIVATE
    CLIENT   | <== SSH ========> |  SERVER  | <== local ==> | SERVER
-------------+              |    +----------+               +---------
                         FIREWALL (only port 443 is open)


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

Usage examples

API allows either initializing the tunnel and starting it or using a with context, which will take care of starting and stopping the tunnel:

Example 1

Code corresponding to Fig1 above follows, given remote server’s address is, password authentication and randomly assigned local bind port.

from sshtunnel import SSHTunnelForwarder

server = SSHTunnelForwarder(
    remote_bind_address=('', 8080)


print(server.local_bind_port)  # show assigned local port
# work with `SECRET SERVICE` through `server.local_bind_port`.


Example 2

Example of a port forwarding to a private server not directly reachable, assuming password protected pkey authentication, remote server’s SSH service is listening on port 443 and that port is open in the firewall (Fig2):

import paramiko
import sshtunnel

with sshtunnel.open_tunnel(
    (REMOTE_SERVER_IP, 443),
    remote_bind_address=(PRIVATE_SERVER_IP, 22),
    local_bind_address=('', 10022)
) as tunnel:
    client = paramiko.SSHClient()
    client.connect('', 10022)
    # do some operations with client session


Example 3

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

from sshtunnel import open_tunnel
from time import sleep

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

    while True:
        # press Ctrl-C for stopping


Or simply using the CLI:

(bash)$ python -m sshtunnel -U vagrant -P vagrant -L :3306 -R -p 2222 localhost

Example 4

Opening an SSH session jumping over two tunnels. SSH transport and tunnels will be daemonised, which will not wait for the connections to stop at close time.

import sshtunnel
from paramiko import SSHClient

with sshtunnel.open_tunnel(
    ssh_address_or_host=('GW1_ip', 20022),
    remote_bind_address=('GW2_ip', 22),
) as tunnel1:
    print('Connection to tunnel1 (GW1_ip:GW1_port) OK...')
    with sshtunnel.open_tunnel(
        ssh_address_or_host=('localhost', tunnel1.local_bind_port),
        remote_bind_address=('target_ip', 22),
    ) as tunnel2:
        print('Connection to tunnel2 (GW2_ip:GW2_port) OK...')
        with SSHClient() as ssh:

CLI usage

$ sshtunnel --help
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 KEY_FILE] [-S KEY_PASSWORD] [-t] [-v]
                 [-V] [-x IP:PORT] [-c SSH_CONFIG_FILE] [-z] [-n]
                 [-d [FOLDER [FOLDER ...]]]

Pure python ssh tunnel utils
Version 0.4.0

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 port is omitted, defaults to 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
                        Elements may also be valid UNIX socket domains:
                        /tmp/foo.sock /tmp/bar.sock ... /tmp/baz.sock
                        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 KEY_FILE, --private_key_file KEY_FILE
                        RSA/DSS/ECDSA private key file
  -S KEY_PASSWORD, --private_key_password KEY_PASSWORD
                        RSA/DSS/ECDSA private key password
  -t, --threaded        Allow concurrent connections to each tunnel
  -v, --verbose         Increase output verbosity (default: ERROR)
  -V, --version         Show version number and quit
  -x IP:PORT, --proxy IP:PORT
                        IP and port of SSH proxy to destination
                        SSH configuration file, defaults to ~/.ssh/config
  -z, --compress        Request server for compression over SSH transport
  -n, --noagent         Disable looking for keys from an SSH agent
  -d [FOLDER [FOLDER ...]], --host_pkey_directories [FOLDER [FOLDER ...]]
                        List of directories where SSH pkeys (in the format `id_*`) may be found

Online documentation

Documentation may be found at readthedocs.



  • v.0.4.0 (Pahaz)
    • Change the daemon mod flag for all tunnel threads (is not fully backward compatible) to prevent unexpected hangs (#219)

    • Add docker based end to end functinal tests for Mongo/Postgres/MySQL (#219)

    • Add docker based end to end hangs tests (#219)

  • v.0.3.2 (Pahaz, JM Fernández)
    • Fix host key directory detection

    • Unify default ssh config folder to ~/.ssh

  • v.0.3.1 (Pahaz)
    • Increase open connection timeout to 10 secods

  • v.0.3.0 (Pahaz)
    • Change default with context behavior to use .stop(force=True) on exit (is not fully backward compatible)

    • Remove useless daemon_forward_servers = True hack for hangs prevention (is not fully backward compatible)

    • Set transport keepalive to 5 second by default (disabled for version < 0.3.0)

    • Set default transport timeout to 0.1

    • Deprecate and remove block_on_close option

    • Fix “deadlocks” / “tunneling hangs” (#173, #201, #162, #211)

  • v.0.2.2 (Pahaz)
    • Add .stop(force=True) for force close active connections (#201)

  • v.0.2.1 (Pahaz, Eddie Chiang and kkrasovskii)
    • Fixes bug with orphan thread for a tunnel that is DOWN (#170)

  • v.0.2.0 (Georgy Rylov)
    • Support IPv6 without proxy command. Use built-in paramiko create socket logic. The logic tries to use ipv6 socket family first, then ipv4 socket family.

  • v.0.1.5 (JM Fernández)
    • Introduce block_on_close attribute

  • v.0.1.4 (Niels Zeilemaker)
    • Allow loading pkeys from ~/.ssh

  • v.0.1.3 (Ignacio Peluffo and others)
    • pkey_file parameter updated to accept relative paths to user folder using ~

    • Several bugfixes

  • v.0.1.2 (JM Fernández)
    • Fix #77

  • v.0.1.1 (JM Fernández)
    • Fix #72

  • v.0.1.0 (JM Fernández)
    • Add tunnel_bindings property

    • Several bugfixes (#49, #56, #57, #59, #60, #62, #64, #66, …) (Pahaz, JM Fernández)

    • Add TRACE logging level (JM Fernández)

    • Code and tests refactoring (JM Fernández)

    • Drop python3.2 support

  • v.0.0.8 (JM Fernández)
  • v.0.0.7 (JM Fernández)
  • v.0.0.6 (Pahaz)
    • add -S CLI options for ssh private key password support (Pahaz)

  • v.0.0.5 (Pahaz)
    • add ssh_proxy argument, as well as ssh_config(5) ProxyCommand support (Lewis Thompson)

    • add some python 2.6 compatibility fixes (Mart Sõmermaa)

    • paramiko.transport inherits handlers of loggers passed to SSHTunnelForwarder (JM Fernández)

    • fix #34, #33, code style and docs (JM Fernández)

    • 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. (Pahaz)
    • fix issue #24 - hide ssh password in logs (Pahaz)

  • v. (Pahaz)
  • v. (Pahaz)
  • v. (Pahaz)
  • v.0.0.4 (Pahaz)
  • v.0.0.3 (Pahaz)
  • v.0.0.1 (Pahaz)
    • SSHTunnelForwarder class (Pahaz)

    • open function (Pahaz)

Project details

Download files

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

Source Distribution

sshtunnel-0.4.0.tar.gz (62.7 kB view hashes)

Uploaded Source

Built Distributions

sshtunnel-0.4.0-py3.8.egg (24.2 kB view hashes)

Uploaded Source

sshtunnel-0.4.0-py2.py3-none-any.whl (24.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page