JumpSSH

1.6.5 verified Fri May 01 auth: no python

JumpSSH is a Python library for executing remote SSH commands and transferring files through a jump host (gateway). Version 1.6.5 supports Python 3.9 and above, with releases approximately every 6 months. It leverages Paramiko for SSH connections and simplifies chaining sessions through multiple hosts.

pip install jumpssh

Common errors

error jumpssh.exceptions.AuthenticationException ↓

cause No SSH agent running or no password/key provided. The library cannot authenticate.

fix

Ensure an SSH agent is running (ssh-agent) and add your private key, or provide password/pkey explicitly in the SSHSession constructor.

error ImportError: cannot import name 'get_remote_session' from 'jumpssh' ↓

cause Using an older version (< 1.2.0?) where get_remote_session was not yet available or was renamed.

fix

Upgrade to latest version: pip install --upgrade jumpssh. In older versions, use SSHSession.get_remote_session() method on a gateway session instead.

error AttributeError: module 'jumpssh' has no attribute 'SSHSession' ↓

cause Trying to import from a submodule incorrectly (e.g., from jumpssh.sessions import SSHSession) or an older version where the API was different.

fix

Use: from jumpssh import SSHSession. If using an old version, upgrade: pip install --upgrade jumpssh.

Warnings

gotcha SSHSession objects may be garbage collected unexpectedly if not referenced, causing automatic session closure. This was fixed in 1.6.4, but ensure you maintain a reference to the session object to avoid premature closing. ↓

fix Upgrade to >= 1.6.4 or keep a strong reference (e.g., store in a list or variable) to prevent GC.

breaking get_remote_session did not respect the 'timeout' parameter before version 1.6.4. If you rely on timeouts, upgrade or implement a workaround. ↓

fix Upgrade to >= 1.6.4 to ensure timeout is honored.

gotcha run_cmd can raise AuthenticationException if no SSH agent is running and no password/key is provided. This was fixed in 1.6.4 to fall back to other auth methods, but you should always provide credentials or have an agent running. ↓

fix Upgrade to >= 1.6.4 or ensure an SSH agent is running and keys are added.

gotcha Transferring binary files with get() failed silently in versions before 1.6.0. The file would be corrupted. Always verify file transfers on older versions. ↓

fix Upgrade to >= 1.6.0 for proper binary file handling.

Imports

SSHSession
wrong
```
from jumpssh.sessions import SSHSession
```
correct
```
from jumpssh import SSHSession
```
The SSHSession class is exposed at the package level, not in a submodule.
get_remote_session
wrong
```
from jumpssh.utils import get_remote_session
```
correct
```
from jumpssh import get_remote_session
```
get_remote_session is a top-level function; it was never in utils.

Quickstart

Connect to a target host through a jump host, run a command, and transfer a file.

from jumpssh import SSHSession

# Establish a session through a jump host
gateway_session = SSHSession(
    'jump.example.com',
    username='jumpuser',
    password=os.environ.get('JUMP_PASSWORD', '')
)

# Open a session to the target server via the gateway
remote_session = gateway_session.get_remote_session(
    'target.example.com',
    username='targetuser',
    password=os.environ.get('TARGET_PASSWORD', '')
)

# Execute a command
result = remote_session.run_cmd('echo hello', timeout=10)
print(result)

# Transfer a file
remote_session.get('/remote/path/file.txt', '/local/path/')

# Close sessions
gateway_session.close()
remote_session.close()