Skip to main content

Pure python SSH tunnels

Project description

[![Circle CI](](

Author: [Pahaz Blinov](


Inspired by but it doesn’t work on Windows. See also:

Require paramiko.


pip install sshtunnel


easy_install sshtunnel

SSH tunnels to remote server

Useful when you need to connect to 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
    SERVER   | <== SSH ========> |  SERVER  | <== local ==> | SERVER
-------------+              |    +----------+               +---------


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

Ex 1

from sshtunnel import SSHTunnelForwarder

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


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


Ex 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 simple use 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 which 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’s ssh_config.

Note ssh_proxy is ignored if ssh_proxy_enabled != True.

ssh_proxy_enabled = True

If true (default) and the 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 which all SSH traffic will be passed through. See the [ssh_proxy](#ssh_proxy) argument for more details.



  • Write tests!


## work in progres ##
  • new feature
## 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)

## v. ##

## v. ##

## v. ##
## 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.6
Filename, size File type Python version Upload date Hashes
Filename, size sshtunnel-0.0.6-py2.py3-none-any.whl (12.3 kB) File type Wheel Python version 3.4 Upload date Hashes View
Filename, size (23.9 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