Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ import { Client } from 'ssh2';
✗ const Client = require('ssh2');
Since v1.0.0, Client is a named export. Older versions might have had it as a default export or directly on the `require('ssh2')` object. Using named import/require is the modern and correct approach.
Server
✓ import { Server } from 'ssh2';
✗ const Server = require('ssh2');
Similar to Client, Server is a named export since v1.0.0. Ensure you destructure it from the module.
utils
✓ import * as utils from 'ssh2/lib/utils';
✗ import { utils } from 'ssh2';
Utility functions like `parseKey` are typically found in a separate `lib/utils` path and imported as a module. Direct named import from `ssh2` might not expose all utilities or could change.
This example demonstrates how to establish an SSH client connection to a server and execute a remote command ('uptime'), logging its standard output and error.
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log(`Stream :: close :: code: ${code}, signal: ${signal}`);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.error('STDERR: ' + data);
});
});
}).on('error', (err) => {
console.error('Client Error:', err.message);
}).connect({
host: process.env.SSH_HOST ?? '127.0.0.1',
port: parseInt(process.env.SSH_PORT ?? '22', 10),
username: process.env.SSH_USERNAME ?? 'user',
privateKey: readFileSync(process.env.SSH_PRIVATE_KEY_PATH ?? './id_rsa')
});
Debug
Known issues
breakingVersion 1.0.0 introduced significant breaking changes. Key classes like `Client` and `Server` became named exports instead of default exports or properties of the main module object. API method signatures, particularly for `Client.exec` and `Client.shell`, changed to pass the stream directly to the callback rather than returning it. `SFTPStream` and `Channel` are no longer directly exported.fixReview the v1.0.0 breaking changes detailed in the GitHub issue #935 (linked in the README) and update import statements and method calls accordingly. Use named imports for `Client` and `Server`.
affects: >=1.0.0
breakingThe `hostVerifier()` client option will now be called every time a handshake occurs, including during rekeying. Ensure your host verification logic handles this repeated invocation.fixAdjust `hostVerifier()` implementations to be idempotent and handle multiple calls per connection, including during rekey events.
affects: >=1.0.0
gotchaNode.js v10.16.0 or newer is required. For Ed25519 key support, Node.js v12.0.0 or newer is necessary.fixEnsure your Node.js environment meets the minimum version requirements. Upgrade Node.js to at least v12.0.0 for full key type compatibility.
affects: <10.16.0 || <12.0.0 for Ed25519
gotchaThe `cpu-features` package is an optional dependency used to optimize cipher list generation. If it fails to install or build, `ssh2` will still function but might use a less optimal default cipher list.fixWhile not strictly required, resolving `cpu-features` installation issues (e.g., build toolchain problems) can improve performance. Check `cpu-features` documentation for its specific system requirements.
affects: >=0.x
Errors
Common errors & fixes
Error: All configured authentication methods failed
The SSH server rejected all attempted authentication methods (e.g., password, private key). This usually means incorrect credentials, an invalid private key, or the server not supporting the client's offered authentication methods.
fixVerify the `username`, `password`, or `privateKey` used in the `connect` options. Ensure the `privateKey` path is correct and the key file is readable by the Node.js process. Check server logs for more details on authentication failures.
Error: connect ECONNREFUSED
The client could not establish a TCP connection to the specified host and port. This typically indicates the SSH server is not running, is not accessible from the client's network, or a firewall is blocking the connection.
fixConfirm the `host` and `port` are correct. Check if the SSH server process is running on the target machine. Verify network connectivity and firewall rules between the client and server.
Error: privateKey is required
The `privateKey` option was provided with an empty or undefined value, or the file path was incorrect leading to an empty buffer.
fixEnsure `privateKey` is correctly populated, either directly with a key string or by reading a valid key file using `readFileSync`. Double-check the path to the private key file.
Audit
Dependencies
cpu-featuresoptionalUsed to help generate an optimal default cipher list. It's an optional package dependency that is automatically built and used if possible.