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().
import { cpSync } from 'node:fs'; cpSync('template', 'my-project', { recursive: true });
Try it
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.
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
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: trueis not the default, unlikemkdirorrm, 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 indestare not removed. - Copying into yourself (
srcinsidedestor the reverse) is rejected. - The
filtersees full paths, both source and destination. Compare withpath.basename()orpath.relative(). The rootsrcitself 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
verbatimSymlinksis 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.