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.
import { copyFileSync } from 'node:fs'; copyFileSync('config.json', 'config.backup.json');
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.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_EXCLwhen losing the destination would be a bug. - Not atomic. If the process dies mid-copy,
destmay be partly written. To publish a file safely, copy to a temporary name andrename()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.