class fabric.connection.Connection(host, user=None, port=None, config=None, gateway=None, forward_agent=None, connect_timeout=None, connect_kwargs=None)

A connection to an SSH daemon, with methods for commands and file transfer.


This class inherits from Invoke’s Context, as it is a context within which commands, tasks etc can operate. It also encapsulates a Paramiko SSHClient instance, performing useful high level operations with that SSHClient and Channel instances generated from it.


Many SSH specific options – such as specifying private keys and passphrases, timeouts, disabling SSH agents, etc – are handled directly by Paramiko and should be specified via the connect_kwargs argument of the constructor.


Connection has a basic “create, connect/open, do work, disconnect/close” lifecycle:

  • Instantiation imprints the object with its connection parameters (but does not actually initiate the network connection).

  • Methods like run, get etc automatically trigger a call to open if the connection is not active; users may of course call open manually if desired.

  • Connections do not always need to be explicitly closed; much of the time, Paramiko’s garbage collection hooks or Python’s own shutdown sequence will take care of things. However, should you encounter edge cases (for example, sessions hanging on exit) it’s helpful to explicitly close connections when you’re done with them.

    This can be accomplished by manually calling close, or by using the object as a contextmanager:

    with Connection('host') as c:'command')


This class rebinds to local so both remote and local command execution can coexist.


Most Connection parameters honor Invoke-style configuration as well as any applicable SSH config file directives. For example, to end up with a connection to admin@myhost, one could:

  • Use any built-in config mechanism, such as /etc/fabric.yml, ~/.fabric.json, collection-driven configuration, env vars, etc, stating user: admin (or {"user": "admin"}, depending on config format.) Then Connection('myhost') would implicitly have a user of admin.
  • Use an SSH config file containing User admin within any applicable Host header (Host myhost, Host *, etc.) Again, Connection('myhost') will default to an admin user.
  • Leverage host-parameter shorthand (described in Config.__init__), i.e. Connection('admin@myhost').
  • Give the parameter directly: Connection('myhost', user='admin').

The same applies to agent forwarding, gateways, and so forth.

New in version 2.0.

__init__(host, user=None, port=None, config=None, gateway=None, forward_agent=None, connect_timeout=None, connect_kwargs=None)

Set up a new object representing a server connection.

  • host (str) –

    the hostname (or IP address) of this connection.

    May include shorthand for the user and/or port parameters, of the form user@host, host:port, or user@host:port.


    Due to ambiguity, IPv6 host addresses are incompatible with the host:port shorthand (though user@host will still work OK). In other words, the presence of >1 : character will prevent any attempt to derive a shorthand port number; use the explicit port parameter instead.


    If host matches a Host clause in loaded SSH config data, and that Host clause contains a Hostname directive, the resulting Connection object will behave as if host is equal to that Hostname value.

    In all cases, the original value of host is preserved as the original_host attribute.

    Thus, given SSH config like so:

    Host myalias
        Hostname realhostname

    a call like Connection(host='myalias') will result in an object whose host attribute is realhostname, and whose original_host attribute is myalias.

  • user (str) – the login user for the remote connection. Defaults to config.user.
  • port (int) – the remote port. Defaults to config.port.
  • config

    configuration settings to use when executing methods on this Connection (e.g. default SSH port and so forth).

    Should be a Config or an invoke.config.Config (which will be turned into a Config).

    Default is an anonymous Config object.

  • gateway

    An object to use as a proxy or gateway for this connection.

    This parameter accepts one of the following:

    • another Connection (for a ProxyJump style gateway);
    • a shell command string (for a ProxyCommand style style gateway).

    Default: None, meaning no gatewaying will occur (unless otherwise configured; if one wants to override a configured gateway at runtime, specify gateway=False.)

  • forward_agent (bool) –

    Whether to enable SSH agent forwarding.

    Default: config.forward_agent.

  • connect_timeout (int) –

    Connection timeout, in seconds.

    Default: config.timeouts.connect.

Parameters:connect_kwargs (dict) –

Keyword arguments handed verbatim to SSHClient.connect (when open is called).

Connection tries not to grow additional settings/kwargs of its own unless it is adding value of some kind; thus, connect_kwargs is currently the right place to hand in paramiko connection parameters such as pkey or key_filename. For example:

c = Connection(
        "key_filename": "/home/myuser/.ssh/private.key",

Default: config.connect_kwargs.

Raises:ValueError – if user or port values are given via both host shorthand and their own arguments. (We refuse the temptation to guess).

Terminate the network connection to the remote end, if open.

If no connection is open, this method does nothing.

New in version 2.0.

forward_local(local_port, remote_port=None, remote_host='localhost', local_host='localhost')

Open a tunnel connecting local_port to the server’s environment.

For example, say you want to connect to a remote PostgreSQL database which is locked down and only accessible via the system it’s running on. You have SSH access to this server, so you can temporarily make port 5432 on your local system act like port 5432 on the server:

import psycopg2
from fabric import Connection

with Connection('my-db-server').forward_local(5432):
    db = psycopg2.connect(
        host='localhost', port=5432, database='mydb'
    # Do things with 'db' here

This method is analogous to using the -L option of OpenSSH’s ssh program.

  • local_port (int) – The local port number on which to listen.
  • remote_port (int) – The remote port number. Defaults to the same value as local_port.
  • local_host (str) – The local hostname/interface on which to listen. Default: localhost.
  • remote_host (str) – The remote hostname serving the forwarded remote port. Default: localhost (i.e., the host this Connection is connected to.)

Nothing; this method is only useful as a context manager affecting local operating system state.

New in version 2.0.

forward_remote(remote_port, local_port=None, remote_host='', local_host='localhost')

Open a tunnel connecting remote_port to the local environment.

For example, say you’re running a daemon in development mode on your workstation at port 8080, and want to funnel traffic to it from a production or staging environment.

In most situations this isn’t possible as your office/home network probably blocks inbound traffic. But you have SSH access to this server, so you can temporarily make port 8080 on that server act like port 8080 on your workstation:

from fabric import Connection

c = Connection('my-remote-server')
with c.forward_remote(8080):"remote-data-writer --port 8080")
    # Assuming remote-data-writer runs until interrupted, this will
    # stay open until you Ctrl-C...

This method is analogous to using the -R option of OpenSSH’s ssh program.

  • remote_port (int) – The remote port number on which to listen.
  • local_port (int) – The local port number. Defaults to the same value as remote_port.
  • local_host (str) – The local hostname/interface the forwarded connection talks to. Default: localhost.
  • remote_host (str) – The remote interface address to listen on when forwarding connections. Default: (i.e. only listen on the remote localhost).

Nothing; this method is only useful as a context manager affecting local operating system state.

New in version 2.0.

get(*args, **kwargs)

Get a remote file to the local filesystem or file-like object.

Simply a wrapper for Transfer.get. Please see its documentation for all details.

New in version 2.0.


Whether or not this connection is actually open.

New in version 2.0.

local(*args, **kwargs)

Execute a shell command on the local system.

This method is effectively a wrapper of; see its docs for details and call signature.

New in version 2.0.


Initiate an SSH connection to the host/port this object is bound to.

This may include activating the configured gateway connection, if one is set.

Also saves a handle to the now-set Transport object for easier access.

Various connect-time settings (and/or their corresponding SSH config options) are utilized here in the call to SSHClient.connect. (For details, see the configuration docs.)

New in version 2.0.


Obtain a socket-like object from gateway.

Returns:A direct-tcpip, if gateway was a Connection; or a ProxyCommand, if gateway was a string.

New in version 2.0.

put(*args, **kwargs)

Put a local file (or file-like object) to the remote filesystem.

Simply a wrapper for Transfer.put. Please see its documentation for all details.

New in version 2.0.

run(command, **kwargs)

Execute a shell command on the remote end of this connection.

This method wraps an SSH-capable implementation of; see its documentation for details.


There are a few spots where Fabric departs from Invoke’s default settings/behaviors; they are documented under Config.global_defaults.

New in version 2.0.


Return a SFTPClient object.

If called more than one time, memoizes the first result; thus, any given Connection instance will only ever have a single SFTP client, and state (such as that managed by chdir) will be preserved.

New in version 2.0.

sudo(command, **kwargs)

Execute a shell command, via sudo, on the remote end.

This method is identical to invoke.context.Context.sudo in every way, except in that – like run – it honors per-host/per-connection configuration overrides in addition to the generic/global ones. Thus, for example, per-host sudo passwords may be configured.

New in version 2.0.