npm / ssh2-sftp-client
ssh2-sftp-client
What changed in ssh2-sftp-client 8 to 12, from its official release notes, upgrade guides and advisories. Also covers @types/ssh2-sftp-client. Sources checked 2026-10-26.
13 breaking1 security5 new APIs and options4 performance3 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initssh2-sftp-client 124 changes
Breaking changes 2
Connection retry support was removed because it added complexity, could leave connection promises pending, and could hurt performance. Users needing retries can add them with a retry promise package.
The project no longer tests against Node.js 18.x and recommends using at least Node.js 20.x.
Fixes and other changes 2
Error handlers now invalidate the SFTP connection when an unexpected ECONNRESET occurs, avoiding delayed timeout errors or hanging promises when the client reuses the connection.
Legitimate remote MS SFTP server connection closures no longer raise an exception.
ssh2-sftp-client 113 changes
Breaking changes 2
Global event listeners no longer raise errors; they log events and invalidate the connection object.
Temporary local event listeners now reject the associated promise for events beyond errors, preventing promises from remaining unfulfilled when servers end connections without an error.
New APIs and options 1
The constructor allows clients to pass custom global event listeners that can take appropriate action for their client.
ssh2-sftp-client 103 changes
Breaking changes 1
Node 18.18.2 or later is highly recommended, and issue reports require Node 18 or later; Node 16.20.2 still appeared to work.
Security 1
Depends on ssh2 1.15.0, which includes a fix for CVE-2023-48795.
New APIs and options 1
Adds a setting to limit concurrent promises used by downloadDir and uploadDir; the default is 10.
ssh2-sftp-client 913 changes
Breaking changes 6
The third argument is now an object with filter, useFastGet, and useFastPut properties instead of a filter function.
The autoClose option is no longer available in options passed to get(); use createReadStream() for low-level control.
list() now accepts a filter function instead of a regular expression to filter returned items.
The end property is no longer supported in pipe() operations used by get() and put(); manage piping manually with getReadStream and getWriteStream for low-level control.
The autoClose option is no longer available in options passed to put(); use createWriteStream() for low-level control.
The third argument is now an object with filter, useFastGet, and useFastPut properties instead of a filter function.
New APIs and options 3
Adds a method that returns a read stream connected to a remote file on the SFTP server.
Adds a method that returns a write stream connected to a remote file on the SFTP server.
Adds a method to create a remote copy of a remote file on the SFTP server.
Performance 3
File transfers now use asynchronous calls to help improve speed.
This version appears to perform significantly better than previous versions, although it was not benchmarked.
File transfers now use asynchronous calls to help improve speed.
Fixes and other changes 1
Retrying a connection after initial failure was refactored and improved to handle retry options more reliably.
ssh2-sftp-client 83 changes
Breaking changes 2
The optional third argument is now a predicate filter function instead of a regular expression, determining which files and directories are included in the transfer.
The optional third argument is now a predicate filter function instead of a regular expression, determining which files and directories are included in the transfer.
Performance 1
Directory tree removal better exploits asynchronous processing, with significant performance improvements observed for broad, shallow trees; the API is unchanged.