Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.cp() method

Reference for fs.cp() and fsPromises.cp() in Node.js: copy files and whole directory trees, filter entries, control overwriting, and handle symlinks.

fs.cp(src, dest[, options], callback) copies a file or a whole directory tree, like the shell's cp -r. It is the built-in replacement for hand-written recursive copy functions and for the fs-extra package's copy().

Directories need the recursive: true option, otherwise copying one is an error. A filter function lets you skip entries, and flags control overwriting. Inside, single files are copied the same way as with copyFile().

NODE
import { cpSync } from 'node:fs';

cpSync('template', 'my-project', { recursive: true });

Try it

Node.js Copying a tree with a filter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Overwrite rules and the directory error

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
fs.cp(src, dest[, options], callback)
fs.cpSync(src, dest[, options]): undefined
fsPromises.cp(src, dest[, options]): Promise<undefined>

// src, dest: string | URL
// options: {
//   recursive?: boolean,             // default false
//   force?: boolean,                 // default true
//   errorOnExist?: boolean,          // default false
//   filter?: (src: string, dest: string) => boolean | Promise<boolean>,
//   dereference?: boolean,           // default false
//   preserveTimestamps?: boolean,    // default false
//   mode?: number,                   // copyFile mode flags, default 0
//   verbatimSymlinks?: boolean       // default false
// }
Option Description
recursive Copy directories and their contents. Required when src is a directory.
force Overwrite existing files. With false, existing files are left alone.
errorOnExist With force: false, throw ERR_FS_CP_EEXIST instead of skipping.
filter Called for every file and directory. Return true to copy, false to skip (skipping a directory skips everything inside). The callback and sync forms need a synchronous filter; the promise form accepts an async one.
dereference Copy the content symlinks point to instead of the links.
preserveTimestamps Keep the source's access and modification times.
mode Flags passed to copyFile (COPYFILE_EXCL, COPYFILE_FICLONE, ...).
verbatimSymlinks Do not rewrite relative link targets to absolute ones.

Returns: nothing.

Errors: ERR_FS_EISDIR (directory without recursive), ERR_FS_CP_EEXIST, ERR_FS_CP_DIR_TO_NON_DIR and ERR_FS_CP_NON_DIR_TO_DIR (type mismatches), ERR_FS_CP_EINVAL (copying a directory into itself), plus the usual ENOENT and EACCES.

Usage notes

  • recursive: true is not the default, unlike mkdir or rm, which surprises people coming from the shell.
  • Existing destination: files are merged in. Existing files are overwritten with the default force: true, but extra files already in dest are not removed.
  • Copying into yourself (src inside dest or the reverse) is rejected.
  • The filter sees full paths, both source and destination. Compare with path.basename() or path.relative(). The root src itself goes through the filter first.
  • Timestamps and ownership are not preserved unless you ask (preserveTimestamps).
  • Symlinks: by default links are copied as links; relative targets are resolved to absolute paths unless verbatimSymlinks is set.
  • Availability: added in Node.js 16.7.0 and no longer experimental in current LTS releases.
  • Not atomic: a failure part-way leaves a partial copy behind.