# SFTP in Python

Upload, download, read and write files on SFTP servers from Python services.

Your services reach SFTP servers through `self.sftp`, looking connections up by the name they were given in the Dashboard or in enmasse.

## Upload and download {#upload-and-download}

```python
from zato.server.service import Service

class SyncInvoices(Service):

    def handle(self):

        conn = self.sftp['My SFTP']

        # Upload a local file to a remote path
        conn.upload('/local/invoices/2026-08.csv', '/incoming/invoices/2026-08.csv')

        # Download a remote file to a local path
        conn.download_file('/outgoing/reports/summary.csv', '/local/reports/summary.csv')
```

## Read and write remote files directly {#read-and-write-remote-files-directly}

No local files are needed - data goes straight between your service and the server. The data is text, bytes, a dict, a list or the service's own input, and the last three are written out as JSON:

```python
from zato.server.service import Service

class ExportOrder(Service):

    def handle(self):

        conn = self.sftp['My SFTP']

        data = self.request.input
        conn.write(data, '/incoming/orders/order-4711.json')

        ack = conn.read('/outgoing/acks/order-4711.txt')
        self.response.payload = {'ack': ack}
```

## Guaranteed delivery {#guaranteed-delivery}

`.publish` spools the data locally and retries until the server accepts it, so the file arrives even if the server is down at the moment of sending:

```python
from zato.server.service import Service

class PublishReport(Service):

    def handle(self):

        conn = self.sftp['My SFTP']
        conn.publish(self.request.input, '/incoming/reports/daily.csv')
```

## List and inspect directories {#list-and-inspect-directories}

```python
from zato.server.service import Service

class ListIncoming(Service):

    def handle(self):

        conn = self.sftp['My SFTP']

        for item in conn.list('/incoming/invoices'):
            self.logger.info('%s %s %s', item.name, item.size_human, item.last_modified)

        if conn.exists('/incoming/invoices/2026-08.csv'):
            conn.move('/incoming/invoices/2026-08.csv', '/archive/invoices/2026-08.csv')
```

## Run SFTP commands {#run-sftp-commands}

Any command the `sftp` binary supports can be executed as well:

```python
from zato.server.service import Service

class CleanUp(Service):

    def handle(self):

        conn = self.sftp['My SFTP']

        out = conn.execute('rm /incoming/tmp/*.part')
        self.logger.info(out.stdout)
```

## Configuration {#configuration}

The [enmasse](https://zato.io/docs/admin/enmasse-reference.html#sftp) YAML for the connection:

```yaml
sftp:
  - name: My SFTP
    address: sftp.example.com:22
    username: zato
    private_key: /keys/id_ed25519
    strict_host_key_checking: true
```

## See also {#see-also}

- [Connection API](https://zato.io/docs/dev/file-transfer/connection-api.html) - Every method of SFTP and SMB connection objects
- [File transfer schedules](https://zato.io/docs/dev/file-transfer/schedules.html) - Have Zato watch a remote directory and invoke a service per file
- [SMB](https://zato.io/docs/dev/examples/smb.html) - The same API against Windows shares
- [Scheduler](https://zato.io/docs/dev/examples/scheduler.html) - Run transfers on an interval or at a specific time

## Learn more {#learn-more}

- [Development documentation](https://zato.io/docs/dev/) - The complete reference for writing services
- [Requests and responses](https://zato.io/docs/dev/request-response/) - What a service receives, what it returns and how both are structured
- [Integration examples](https://zato.io/docs/dev/examples/) - Ready-made code for the systems you are likely to connect to
- [IDE and debugging](https://zato.io/docs/dev/ide/) - Write services in the Dashboard or in your own editor
- [Data models](https://zato.io/docs/dev/model/) - Declare inputs and outputs and have them validated for you
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - The full platform tutorial, from installation to production patterns