Skip to content
ZestSSH Docs

Parallel Transfers

When you need to download or upload multiple files, ZestSSH processes them concurrently rather than one at a time. This significantly reduces total transfer time, especially when working with many small files or over connections with available bandwidth headroom.

How it works

Section titled “How it works”

ZestSSH uses a managed transfer queue with a concurrency limit. The default maximum is 3 simultaneous transfers in the desktop dual-pane interface. When you initiate a batch transfer (multi-select download, drag-and-drop of several files, or queuing multiple uploads), the process works as follows:

  1. Queue creation. Each file is added to the transfer queue as a pending item with its source path, destination path, file name, direction (upload or download), and expected size.
  2. Concurrent execution. The queue processor picks up pending items and starts them, up to the concurrency limit. As soon as one transfer completes (or fails), the next pending item starts.
  3. Per-file progress. Each active transfer reports its own bytes transferred, which the UI displays as an individual progress bar in the transfer queue panel.
  4. Aggregate progress. For programmatic parallel downloads via SFTPParallelTransfer, ZestSSH pre-stats all remote files to determine total bytes across the batch, then reports aggregate progress as a fraction of that total. This gives you a single progress indicator that represents the entire batch.
  5. Completion. When all transfers finish, both the local and remote file panes refresh automatically to reflect the new state.

The SFTPParallelTransfer engine

Section titled “The SFTPParallelTransfer engine”

Under the hood, the SFTPParallelTransfer class powers batch downloads with the following behavior:

  • Configurable concurrency. The maxConcurrent parameter controls how many files download simultaneously. The default is 4 for the core engine. The desktop UI sets its own limit of 3 for the visual transfer queue.
  • Pre-stat for sizing. Before any transfer begins, the engine stats all remote files in parallel to determine each file’s size. This allows accurate aggregate progress reporting from the start.
  • Directory creation. If the local destination directory does not exist, it is created automatically.
  • Resume semantics. If a local file already exists at the destination, the parallel engine appends to it rather than truncating, providing implicit resume behavior for interrupted batch transfers.
  • Per-file results. Each file produces an SFTPTransferResult containing the remote path, local path, success status, bytes transferred, elapsed time, and any error message. Results are returned in the same order as the input paths.

Transfer queue panel (desktop)

Section titled “Transfer queue panel (desktop)”

On desktop, the transfer queue panel sits at the bottom of the dual-pane SFTP screen and shows all queued transfers:

ColumnDescription
File nameThe name of the file being transferred.
DirectionUpload (arrow up) or download (arrow down).
ProgressA progress bar with bytes transferred and percentage.
StatusPending (waiting), Active (in progress), Completed, Failed, or Cancelled.

Actions available in the queue:

  • Cancel: Stop an active or pending transfer. The file’s status changes to Cancelled.
  • Retry: Re-queue a failed transfer. It resets to Pending and enters the queue again.
  • Clear Completed: Remove all completed, failed, and cancelled entries from the queue to clean up the list.

Tips for large batch transfers

Section titled “Tips for large batch transfers”
  • Start with a manageable batch. If you are transferring hundreds of files, consider breaking them into smaller groups so you can monitor progress and catch failures early.
  • Watch for failures. The transfer queue shows failed items with an error message. Common causes include permission denied, disk full, or the remote file being deleted mid-transfer. Use the Retry action to re-attempt failed files.
  • Bandwidth sharing. Three concurrent transfers share the SSH connection’s bandwidth. On slow connections, you may see each individual transfer move slower than a single transfer would, but the total throughput and batch completion time improve.
Section titled “Related”