{"id":15623,"library":"ftp","title":"Node.js FTP Client","description":"This is an FTP client module for Node.js, providing an asynchronous interface for communicating with FTP servers. The latest stable version, 0.3.10, was last published in February 2016, making it a very old and unmaintained package. It primarily supports older Node.js versions (>=0.8.0) and exclusively uses CommonJS modules. It offers core FTP operations such as listing directories, downloading, and uploading files through an event-driven API. While it was a foundational FTP client in early Node.js ecosystems, it lacks modern features, security updates, and active maintenance compared to newer, actively developed alternatives like `basic-ftp` or `promise-ftp`.","status":"abandoned","version":"0.3.10","language":"javascript","source_language":"en","source_url":"http://github.com/mscdex/node-ftp","tags":["javascript","ftp","client","transfer"],"install":[{"cmd":"npm install ftp","lang":"bash","label":"npm"},{"cmd":"yarn add ftp","lang":"bash","label":"yarn"},{"cmd":"pnpm add ftp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for regular expression parsing, likely in FTP response handling.","package":"xregexp","optional":false},{"reason":"Provides a consistent stream API across different Node.js versions.","package":"readable-stream","optional":false}],"imports":[{"note":"The package is CommonJS-only (published in 2016) and does not support ES Modules `import` syntax. Attempting to use `import` will result in a runtime error.","wrong":"import { Client } from 'ftp'","symbol":"Client","correct":"const Client = require('ftp')"},{"note":"The `Client` symbol is a constructor function exported directly from the main module. There is no default export, and it must be instantiated with `new Client()`.","wrong":"import Client from 'ftp';","symbol":"Client (type/constructor)","correct":"const Client = require('ftp');\nconst c = new Client();"},{"note":"The client uses an event-driven pattern, emitting events like `ready`, `error`, `greeting`, `close`, and `end`. Correctly handling the `error` event is crucial.","symbol":"Events","correct":"c.on('ready', () => { /* ... */ });\nc.on('error', (err) => { /* ... */ });"}],"quickstart":{"code":"const Client = require('ftp');\nconst fs = require('fs');\n\nconst FTP_HOST = process.env.FTP_HOST ?? 'localhost';\nconst FTP_PORT = parseInt(process.env.FTP_PORT ?? '21', 10);\nconst FTP_USER = process.env.FTP_USER ?? 'anonymous';\nconst FTP_PASSWORD = process.env.FTP_PASSWORD ?? 'anonymous@';\nconst REMOTE_FILE = process.env.REMOTE_FILE ?? 'remote-file.txt';\nconst LOCAL_COPY_FILE = process.env.LOCAL_COPY_FILE ?? 'local-copy.txt';\n\nconst c = new Client();\nc.on('ready', function() {\n  console.log(`Connected to ${FTP_HOST}:${FTP_PORT}. Attempting to download ${REMOTE_FILE}...`);\n  c.get(REMOTE_FILE, function(err, stream) {\n    if (err) {\n      console.error('Error downloading file:', err.message, err.code ? `(Code: ${err.code})` : '');\n      c.end();\n      return;\n    }\n    stream.once('close', function() {\n      console.log(`Successfully downloaded ${REMOTE_FILE} to ${LOCAL_COPY_FILE}.`);\n      c.end();\n    });\n    stream.pipe(fs.createWriteStream(LOCAL_COPY_FILE));\n  });\n});\n\nc.on('error', function(err) {\n  console.error('FTP Client Error:', err.message, err.code ? `(Code: ${err.code})` : '');\n});\n\nc.on('end', function() {\n  console.log('FTP connection ended.');\n});\n\nc.on('close', function(hadErr) {\n  console.log('FTP connection closed. Had error:', hadErr);\n});\n\nc.connect({\n  host: FTP_HOST,\n  port: FTP_PORT,\n  user: FTP_USER,\n  password: FTP_PASSWORD,\n  secure: false // Set to 'true' or 'control' for FTPS, 'implicit' for implicit FTPS (deprecated)\n});","lang":"javascript","description":"This example demonstrates connecting to an FTP server, downloading a specified remote file, and saving it to the local filesystem using streams. It includes error handling and utilizes environment variables for connection configuration."},"warnings":[{"fix":"Prefer `secure: true` for explicit FTPS (AUTH TLS) or `secure: 'control'` if only the control connection needs encryption. For new projects, consider modern FTP client libraries like `basic-ftp` that offer better TLS support.","message":"The `secure` option's `'implicit'` value for implicitly encrypted control connections is deprecated in modern FTP/FTPS contexts and may not work reliably with contemporary servers or Node.js TLS versions.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"For new projects, use actively maintained Node.js FTP/FTPS client libraries such as `basic-ftp` which supports modern features like Promises, async/await, FTPS, and TypeScript.","message":"This package is unmaintained, with the last release in 2016 and last commit in 2018. It does not receive security updates or bug fixes, making it potentially vulnerable to discovered FTP protocol exploits or Node.js compatibility issues.","severity":"gotcha","affected_versions":">=0.3.10"},{"fix":"Ensure your project or file uses CommonJS (`.js` files without `\"type\": \"module\"` in `package.json`, or `.cjs` files) and imports the library using `const Client = require('ftp');`.","message":"The library exclusively uses CommonJS `require()` syntax and does not support ES Modules (`import`). Attempting to use `import` will lead to runtime errors in modern Node.js environments configured for ESM.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Increase `connTimeout` and `pasvTimeout` values in the `connect()` configuration object to accommodate network conditions, e.g., `{ connTimeout: 30000, pasvTimeout: 30000 }`.","message":"The `connTimeout` and `pasvTimeout` configurations default to 10 seconds. In environments with high latency or strict firewalls, these timeouts might be insufficient, leading to connection or data transfer failures.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure your file is treated as CommonJS and use `const Client = require('ftp');` to import the module. The `Client` is directly the exported constructor.","cause":"Attempting to use `new Client()` after importing `ftp` with an `import` statement in an ESM context, or incorrectly destructuring the CommonJS export.","error":"TypeError: require(...) is not a constructor"},{"fix":"Verify the `host` and `port` in your `connect()` configuration. Check if the FTP server is running and accessible from the client's network. Increase `connTimeout` if network latency is expected.","cause":"The client failed to establish a connection to the FTP server within the specified `connTimeout` period, often due to an incorrect host/port, server not running, or network/firewall issues.","error":"Error: connect ETIMEDOUT"},{"fix":"Inspect the `err.code` property for the specific FTP response code. Check server logs for more details. If using TLS, ensure compatible `secure` options and `secureOptions` are set, as older libraries might struggle with modern TLS versions/configs.","cause":"A generic FTP protocol error, often indicating a problem during the FTP command/response sequence, potentially related to server misconfiguration, unsupported features, or deprecated TLS settings. Error objects usually contain a `code` property for the FTP response code.","error":"Error: EPROTO: protocol error, errno -1"},{"fix":"While this warning might not immediately break functionality, it highlights the package's outdated dependencies. There is no direct fix within `node-ftp` itself. Consider migrating to a modern, actively maintained FTP client like `basic-ftp` which uses up-to-date Node.js APIs.","cause":"This warning indicates that the underlying Node.js `tls` module methods used by `node-ftp` for establishing secure connections are deprecated in newer Node.js versions. This is due to the package's age.","error":"DEP0064] DeprecationWarning: tls.createSecurePair() is deprecated. Please use tls.TLSSocket instead."}],"ecosystem":"npm"}