Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.copyFile() method

Reference for fs.copyFile() in Node.js: copy one file to another path, refuse to overwrite with COPYFILE_EXCL, and understand what is and is not copied.

fs.copyFile(src, dest[, mode], callback) copies a single file. The operating system does the work (often with an efficient kernel copy), so no data passes through JavaScript and memory use stays flat even for huge files. By default an existing destination is overwritten.

It copies files only. To copy a directory tree use fs.cp(). The mode argument is a bit mask of flags from fs.constants that makes the copy fail if the target exists or asks the file system for a copy-on-write clone.

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

copyFileSync('config.json', 'config.backup.json');

Try it

Node.js Copying, overwriting and refusing to overwrite

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 The promise version and error cases

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.copyFile(src, dest[, mode], callback)
fs.copyFileSync(src, dest[, mode]): undefined
fsPromises.copyFile(src, dest[, mode]): Promise<undefined>

// src, dest: string | Buffer | URL
// mode: integer (default 0), a bit mask of:
//   fs.constants.COPYFILE_EXCL
//   fs.constants.COPYFILE_FICLONE
//   fs.constants.COPYFILE_FICLONE_FORCE
Name Description
src Path of the file to copy.
dest Path of the copy. Created or overwritten.
mode Optional flags, combined with bitwise OR.|`.
Flag Meaning
COPYFILE_EXCL Fail with EEXIST if dest already exists.
COPYFILE_FICLONE Try a copy-on-write clone (reflink); fall back to a normal copy if the file system cannot do it.
COPYFILE_FICLONE_FORCE Require a clone; fail if the file system cannot do it.

Returns: nothing (undefined).

Errors: ENOENT (missing source or destination directory), EEXIST (with COPYFILE_EXCL), EISDIR or EPERM-style errors when the source is a directory, EACCES, ENOSPC, ENOTSUP (forced clone unsupported).

Usage notes

  • Overwrites silently. Add COPYFILE_EXCL when losing the destination would be a bug.
  • Not atomic. If the process dies mid-copy, dest may be partly written. To publish a file safely, copy to a temporary name and rename() it.
  • Metadata: the content and permission bits are copied; timestamps and ownership are not preserved. Use fs.utimes() afterwards if you need the same times.
  • Same file: copying a file onto itself is an error or a no-op depending on the platform, so compare paths first.
  • Symbolic links: the link is followed, so the copy is a regular file with the target's content.
  • Cloning makes the copy instant and space-free on file systems such as Btrfs, XFS (with reflinks), APFS and ReFS. Later edits to either file are independent.
  • Directories: use fs.cp(). For custom behaviour (progress, transforms) use streams with `pipeline()Optional flags, combined with bitwise OR.