SSH with paramiko Part 2: SFTP File Transfer

By the end of this lesson you can:

• Open an SFTP session over an existing SSH connection.
• Upload (put) and download (get) files.
• List, stat, and create remote directories.
• Transfer whole folder trees and verify transfers by size/hash.

Old FTP sent files (and passwords!) in plaintext. SFTP is completely different: it's a file-transfer protocol that runs over SSH, so it's encrypted and uses the same key-based auth you set up last lesson. Same connection, new capability.

Opening SFTP

import paramiko, os

client = paramiko.SSHClient()
client.load_system_host_keys()
client.set_missing_host_key_policy(paramiko.RejectPolicy())
client.connect(os.environ["SSH_HOST"], username=os.environ["SSH_USER"],
               key_filename=os.environ["SSH_KEY"], timeout=15)

sftp = client.open_sftp()        # the file-transfer session
# …transfer files…
sftp.close()
client.close()

SFTP rides the connection you already opened — no second login, same encryption and auth.

Upload & download

sftp.put("local/report.pdf", "/srv/reports/report.pdf")   # upload
sftp.get("/var/log/app.log", "downloads/app.log")        # download

put(local, remote) uploads; get(remote, local) downloads. Paths are strings; remote paths are usually absolute. The remote parent folder must already exist.

Listing & inspecting

for name in sftp.listdir("/srv/reports"):       # just names
    print(name)

for attr in sftp.listdir_attr("/srv/reports"):  # names + metadata
    print(attr.filename, attr.st_size, attr.st_mtime)

info = sftp.stat("/srv/reports/report.pdf")     # one file's metadata
print(info.st_size)

This mirrors Lesson 6's local file inspection — st_size, st_mtime — but on the remote machine.

Making remote directories

def ensure_remote_dir(sftp, remote_dir: str) -> None:
    """mkdir -p for SFTP: create each path segment if missing."""
    parts = remote_dir.strip("/").split("/")
    path = ""
    for part in parts:
        path += "/" + part
        try:
            sftp.stat(path)        # already exists?
        except FileNotFoundError:
            sftp.mkdir(path)

SFTP's mkdir doesn't create parents, so this helper walks the path and makes each missing segment — the remote mkdir -p.

Verifying a transfer

from pathlib import Path

def put_verified(sftp, local: str, remote: str) -> bool:
    sftp.put(local, remote)
    local_size = Path(local).stat().st_size
    remote_size = sftp.stat(remote).st_size
    if local_size != remote_size:
        raise IOError(f"size mismatch: {local_size} != {remote_size}")
    return True

Goal: take last night's local backup (Lesson 38/39), upload it to a remote server into a dated folder, verify it, and prune old remote backups — the "1 off-site copy" of the 3-2-1 rule.

import os, logging
from pathlib import Path
from datetime import datetime
from contextlib import contextmanager
import paramiko

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
log = logging.getLogger("offsite")

@contextmanager
def sftp_session():
    client = paramiko.SSHClient()
    client.load_system_host_keys()
    client.set_missing_host_key_policy(paramiko.RejectPolicy())
    client.connect(os.environ["SSH_HOST"], username=os.environ["SSH_USER"],
                   key_filename=os.environ["SSH_KEY"], timeout=15)
    sftp = client.open_sftp()
    try:
        yield client, sftp
    finally:
        sftp.close(); client.close()

def ensure_remote_dir(sftp, path: str):
    cur = ""
    for part in path.strip("/").split("/"):
        cur += "/" + part
        try: sftp.stat(cur)
        except FileNotFoundError: sftp.mkdir(cur)

def upload_backup(local_file: str, remote_root: str, keep: int = 7) -> None:
    local = Path(local_file)
    stamp = datetime.now().strftime("%Y%m%d")
    remote_dir = f"{remote_root}/{stamp}"
    remote_path = f"{remote_dir}/{local.name}"

    with sftp_session() as (client, sftp):
        ensure_remote_dir(sftp, remote_dir)
        sftp.put(str(local), remote_path)

        # verify by size
        if sftp.stat(remote_path).st_size != local.stat().st_size:
            raise IOError("size mismatch — upload incomplete")
        log.info("uploaded %s → %s (%.1f KB)", local.name, remote_path,
                 local.stat().st_size / 1000)

        # rotate remote backups: keep newest <keep> dated folders
        dated = sorted(d for d in sftp.listdir(remote_root))
        for old in dated[:-keep]:
            _, _, err = (client.exec_command(f"rm -rf '{remote_root}/{old}'"))
            log.info("pruned remote %s", old)

upload_backup("backups/db/app-20260528.db.gz", "/srv/offsite/db", keep=7)

INFO uploaded app-20260528.db.gz → /srv/offsite/db/20260528/app-20260528.db.gz (148.2 KB)
INFO pruned remote 20260520

Read the code

This combines both halves of paramiko: SFTP put for the transfer, and exec_command (Lesson 41) to rm -rf old remote folders for rotation. The context manager closes both the SFTP and SSH sessions, ensure_remote_dir creates the dated path, and the size check refuses to trust a partial upload. Schedule this after your local DB backup (Lessons 36, 39) and you've automated the off-site copy that survives your building burning down — the most important backup of all.

Use the same target as Lesson 41 (VM, Pi, or localhost SFTP).

from datetime import datetime
items = sftp.listdir_attr("/srv/data")
for a in sorted(items, key=lambda x: x.st_size, reverse=True):
    when = datetime.fromtimestamp(a.st_mtime)
    print(f"{a.st_size:>10} {when:%Y-%m-%d} {a.filename}")

from pathlib import Path
def put_tree(sftp, local_dir, remote_dir):
    base = Path(local_dir)
    for f in base.rglob("*"):
        if f.is_file():
            rel = f.relative_to(base).as_posix()
            target = f"{remote_dir}/{rel}"
            ensure_remote_dir(sftp, target.rsplit("/", 1)[0])
            sftp.put(str(f), target)

SFTP transfers files securely over the same SSH channel: client.open_sftp() gives a session with a pathlib-like API — put (upload), get (download), listdir/listdir_attr/stat (inspect), mkdir (no parents, so write your own mkdir -p). Always verify transfers — size at minimum, hashes for real integrity — because a dropped connection truncates silently. Combine SFTP transfers with Lesson 41's exec_command for full remote control: upload a deploy, run it, verify it. Off-site backup uploads are the killer app — the "1" in 3-2-1.