Class:FileHandle#

A<FileHandle> object is an object wrapper for a numeric file descriptor.

Instances of the<FileHandle> object are created by thefsPromises.open()method.

All<FileHandle> objects are<EventEmitter>s.

If a<FileHandle> is not closed using thefilehandle.close() method, it willtry to automatically close the file descriptor and emit a process warning,helping to prevent memory leaks. Please do not rely on this behavior becauseit can be unreliable and the file may not be closed. Instead, always explicitlyclose<FileHandle>s. Node.js may change this behavior in the future.

import { open }from'node:fs/promises';let filehandle;try {  filehandle =awaitopen('thefile.txt','r');}finally {await filehandle?.close();}copy

import { open }from'node:fs/promises';const fd =awaitopen('/dev/input/event0');// Create a stream from some character device.const stream = fd.createReadStream();setTimeout(() => {  stream.close();// This may not close the stream.// Artificially marking end-of-stream, as if the underlying resource had// indicated end-of-file by itself, allows the stream to close.// This does not cancel pending read operations, and if there is such an// operation, the process may still not be able to exit successfully// until it finishes.  stream.push(null);  stream.read(0);},100);copy

import { open }from'node:fs/promises';const fd =awaitopen('sample.txt');fd.createReadStream({start:90,end:99 });copy

import {  open,}from'node:fs/promises';const file =awaitopen('./some/file/to/read');forawait (const chunkof file.readableWebStream())console.log(chunk);await file.close();const {  open,} =require('node:fs/promises');(async () => {const file =awaitopen('./some/file/to/read');forawait (const chunkof file.readableWebStream())console.log(chunk);await file.close();})();copy

import { open }from'node:fs/promises';const file =awaitopen('./some/file/to/read');forawait (const lineof file.readLines()) {console.log(line);}const { open } =require('node:fs/promises');(async () => {const file =awaitopen('./some/file/to/read');forawait (const lineof file.readLines()) {console.log(line);  }})();copy

import { open }from'node:fs/promises';let filehandle =null;try {  filehandle =awaitopen('temp.txt','r+');await filehandle.truncate(4);}finally {await filehandle?.close();}copy

fsPromises.access(path[, mode])#

• path<string> |<Buffer> |<URL>
• mode<integer>Default:fs.constants.F_OK
• Returns:<Promise> Fulfills withundefined upon success.

Tests a user's permissions for the file or directory specified bypath.Themode argument is an optional integer that specifies the accessibilitychecks to be performed.mode should be either the valuefs.constants.F_OKor a mask consisting of the bitwise OR of any offs.constants.R_OK,fs.constants.W_OK, andfs.constants.X_OK (e.g.fs.constants.W_OK | fs.constants.R_OK). CheckFile access constants forpossible values ofmode.

If the accessibility check is successful, the promise is fulfilled with novalue. If any of the accessibility checks fail, the promise is rejectedwith an<Error> object. The following example checks if the file/etc/passwd can be read and written by the current process.

import { access, constants }from'node:fs/promises';try {awaitaccess('/etc/passwd', constants.R_OK | constants.W_OK);console.log('can access');}catch {console.error('cannot access');}copy

UsingfsPromises.access() to check for the accessibility of a file beforecallingfsPromises.open() is not recommended. Doing so introduces a racecondition, since other processes may change the file's state between the twocalls. Instead, user code should open/read/write the file directly and handlethe error raised if the file is not accessible.

fsPromises.appendFile(path, data[, options])#

• path<string> |<Buffer> |<URL> |<FileHandle> filename or<FileHandle>
• data<string> |<Buffer>
• options<Object> |<string>
  • encoding<string> |<null>Default:'utf8'
  • mode<integer>Default:0o666
  • flag<string> Seesupport of file systemflags.Default:'a'.
  • flush<boolean> Iftrue, the underlying file descriptor is flushedprior to closing it.Default:false.
• Returns:<Promise> Fulfills withundefined upon success.

Asynchronously append data to a file, creating the file if it does not yetexist.data can be a string or a<Buffer>.

Ifoptions is a string, then it specifies theencoding.

Themode option only affects the newly created file. Seefs.open()for more details.

Thepath may be specified as a<FileHandle> that has been openedfor appending (usingfsPromises.open()).

fsPromises.chmod(path, mode)#

• path<string> |<Buffer> |<URL>
• mode<string> |<integer>
• Returns:<Promise> Fulfills withundefined upon success.

Changes the permissions of a file.

fsPromises.chown(path, uid, gid)#

• path<string> |<Buffer> |<URL>
• uid<integer>
• gid<integer>
• Returns:<Promise> Fulfills withundefined upon success.

Changes the ownership of a file.

fsPromises.copyFile(src, dest[, mode])#

• src<string> |<Buffer> |<URL> source filename to copy
• dest<string> |<Buffer> |<URL> destination filename of the copy operation
• mode<integer> Optional modifiers that specify the behavior of the copyoperation. It is possible to create a mask consisting of the bitwise OR oftwo or more values (e.g.fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)Default:0.
  • fs.constants.COPYFILE_EXCL: The copy operation will fail ifdestalready exists.
  • fs.constants.COPYFILE_FICLONE: The copy operation will attempt to createa copy-on-write reflink. If the platform does not support copy-on-write,then a fallback copy mechanism is used.
  • fs.constants.COPYFILE_FICLONE_FORCE: The copy operation will attempt tocreate a copy-on-write reflink. If the platform does not supportcopy-on-write, then the operation will fail.
• Returns:<Promise> Fulfills withundefined upon success.

Asynchronously copiessrc todest. By default,dest is overwritten if italready exists.

No guarantees are made about the atomicity of the copy operation. If anerror occurs after the destination file has been opened for writing, an attemptwill be made to remove the destination.

import { copyFile, constants }from'node:fs/promises';try {awaitcopyFile('source.txt','destination.txt');console.log('source.txt was copied to destination.txt');}catch {console.error('The file could not be copied');}// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.try {awaitcopyFile('source.txt','destination.txt', constants.COPYFILE_EXCL);console.log('source.txt was copied to destination.txt');}catch {console.error('The file could not be copied');}copy

fsPromises.cp(src, dest[, options])#

• src<string> |<URL> source path to copy.
• dest<string> |<URL> destination path to copy to.
• options<Object>
  • dereference<boolean> dereference symlinks.Default:false.
  • errorOnExist<boolean> whenforce isfalse, and the destinationexists, throw an error.Default:false.
  • filter<Function> Function to filter copied files/directories. Returntrue to copy the item,false to ignore it. When ignoring a directory,all of its contents will be skipped as well. Can also return aPromisethat resolves totrue orfalseDefault:undefined.
    • src<string> source path to copy.
    • dest<string> destination path to copy to.
    • Returns:<boolean> |<Promise> A value that is coercible toboolean oraPromise that fulfils with such value.
  • force<boolean> overwrite existing file or directory. The copyoperation will ignore errors if you set this to false and the destinationexists. Use theerrorOnExist option to change this behavior.Default:true.
  • mode<integer> modifiers for copy operation.Default:0.Seemode flag offsPromises.copyFile().
  • preserveTimestamps<boolean> Whentrue timestamps fromsrc willbe preserved.Default:false.
  • recursive<boolean> copy directories recursivelyDefault:false
  • verbatimSymlinks<boolean> Whentrue, path resolution for symlinks willbe skipped.Default:false
• Returns:<Promise> Fulfills withundefined upon success.

Asynchronously copies the entire directory structure fromsrc todest,including subdirectories and files.

When copying a directory to another directory, globs are not supported andbehavior is similar tocp dir1/ dir2/.

fsPromises.glob(pattern[, options])#

• pattern<string> |<string[]>
• options<Object>
  • cwd<string> |<URL> current working directory.Default:process.cwd()
  • exclude<Function> |<string[]> Function to filter out files/directories or alist of glob patterns to be excluded. If a function is provided, returntrue to exclude the item,false to include it.Default:undefined.If a string array is provided, each string should be a glob pattern thatspecifies paths to exclude. Note: Negation patterns (e.g., '!foo.js') arenot supported.
  • withFileTypes<boolean>true if the glob should return paths as Dirents,false otherwise.Default:false.
• Returns:<AsyncIterator> An AsyncIterator that yields the paths of filesthat match the pattern.

import { glob }from'node:fs/promises';forawait (const entryofglob('**/*.js'))console.log(entry);const { glob } =require('node:fs/promises');(async () => {forawait (const entryofglob('**/*.js'))console.log(entry);})();copy

fsPromises.lchmod(path, mode)#

• path<string> |<Buffer> |<URL>
• mode<integer>
• Returns:<Promise> Fulfills withundefined upon success.

Changes the permissions on a symbolic link.

This method is only implemented on macOS.

fsPromises.lchown(path, uid, gid)#

• path<string> |<Buffer> |<URL>
• uid<integer>
• gid<integer>
• Returns:<Promise> Fulfills withundefined upon success.

Changes the ownership on a symbolic link.

fsPromises.lutimes(path, atime, mtime)#

• path<string> |<Buffer> |<URL>
• atime<number> |<string> |<Date>
• mtime<number> |<string> |<Date>
• Returns:<Promise> Fulfills withundefined upon success.

Changes the access and modification times of a file in the same way asfsPromises.utimes(), with the difference that if the path refers to asymbolic link, then the link is not dereferenced: instead, the timestamps ofthe symbolic link itself are changed.

fsPromises.link(existingPath, newPath)#

• existingPath<string> |<Buffer> |<URL>
• newPath<string> |<Buffer> |<URL>
• Returns:<Promise> Fulfills withundefined upon success.

Creates a new link from theexistingPath to thenewPath. See the POSIXlink(2) documentation for more detail.

fsPromises.lstat(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.Stats> object should bebigint.Default:false.
• Returns:<Promise> Fulfills with the<fs.Stats> object for the givensymbolic linkpath.

Equivalent tofsPromises.stat() unlesspath refers to a symbolic link,in which case the link itself is stat-ed, not the file that it refers to.Refer to the POSIXlstat(2) document for more detail.

fsPromises.mkdir(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object> |<integer>
  • recursive<boolean>Default:false
  • mode<string> |<integer> Not supported on Windows.Default:0o777.
• Returns:<Promise> Upon success, fulfills withundefined ifrecursiveisfalse, or the first directory path created ifrecursive istrue.

Asynchronously creates a directory.

The optionaloptions argument can be an integer specifyingmode (permissionand sticky bits), or an object with amode property and arecursiveproperty indicating whether parent directories should be created. CallingfsPromises.mkdir() whenpath is a directory that exists results in arejection only whenrecursive is false.

import { mkdir }from'node:fs/promises';try {const projectFolder =newURL('./test/project/',import.meta.url);const createDir =awaitmkdir(projectFolder, {recursive:true });console.log(`created${createDir}`);}catch (err) {console.error(err.message);}const { mkdir } =require('node:fs/promises');const { join } =require('node:path');asyncfunctionmakeDirectory() {const projectFolder =join(__dirname,'test','project');const dirCreation =awaitmkdir(projectFolder, {recursive:true });console.log(dirCreation);return dirCreation;}makeDirectory().catch(console.error);copy

fsPromises.mkdtemp(prefix[, options])#

• prefix<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• Returns:<Promise> Fulfills with a string containing the file system pathof the newly created temporary directory.

Creates a unique temporary directory. A unique directory name is generated byappending six random characters to the end of the providedprefix. Due toplatform inconsistencies, avoid trailingX characters inprefix. Someplatforms, notably the BSDs, can return more than six random characters, andreplace trailingX characters inprefix with random characters.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use.

import { mkdtemp }from'node:fs/promises';import { join }from'node:path';import { tmpdir }from'node:os';try {awaitmkdtemp(join(tmpdir(),'foo-'));}catch (err) {console.error(err);}copy

ThefsPromises.mkdtemp() method will append the six randomly selectedcharacters directly to theprefix string. For instance, given a directory/tmp, if the intention is to create a temporary directorywithin/tmp, theprefix must end with a trailing platform-specific path separator(require('node:path').sep).

fsPromises.mkdtempDisposable(prefix[, options])#

• prefix<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• Returns:<Promise> Fulfills with a Promise for an async-disposable Object:
  • path<string> The path of the created directory.
  • remove<AsyncFunction> A function which removes the created directory.
  • [Symbol.asyncDispose]<AsyncFunction> The same asremove.

The resulting Promise holds an async-disposable object whosepath propertyholds the created directory path. When the object is disposed, the directoryand its contents will be removed asynchronously if it still exists. If thedirectory cannot be deleted, disposal will throw an error. The object has anasyncremove() method which will perform the same task.

Both this function and the disposal function on the resulting object areasync, so it should be used withawait +await using as inawait using dir = await fsPromises.mkdtempDisposable('prefix').

For detailed information, see the documentation offsPromises.mkdtemp().

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use.

fsPromises.open(path, flags[, mode])#

• path<string> |<Buffer> |<URL>
• flags<string> |<number> Seesupport of file systemflags.Default:'r'.
• mode<string> |<integer> Sets the file mode (permission and sticky bits)if the file is created.Default:0o666 (readable and writable)
• Returns:<Promise> Fulfills with a<FileHandle> object.

Opens a<FileHandle>.

Refer to the POSIXopen(2) documentation for more detail.

Some characters (< > : " / \ | ? *) are reserved under Windows as documentedbyNaming Files, Paths, and Namespaces. Under NTFS, if the filename containsa colon, Node.js will open a file system stream, as described bythis MSDN page.

fsPromises.opendir(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • encoding<string> |<null>Default:'utf8'
  • bufferSize<number> Number of directory entries that are bufferedinternally when reading from the directory. Higher values lead to betterperformance but higher memory usage.Default:32
  • recursive<boolean> ResolvedDir will be an<AsyncIterable>containing all sub files and directories.Default:false
• Returns:<Promise> Fulfills with an<fs.Dir>.

Asynchronously open a directory for iterative scanning. See the POSIXopendir(3) documentation for more detail.

Creates an<fs.Dir>, which contains all further functions for reading fromand cleaning up the directory.

Theencoding option sets the encoding for thepath while opening thedirectory and subsequent read operations.

Example using async iteration:

import { opendir }from'node:fs/promises';try {const dir =awaitopendir('./');forawait (const direntof dir)console.log(dirent.name);}catch (err) {console.error(err);}copy

When using the async iterator, the<fs.Dir> object will be automaticallyclosed after the iterator exits.

fsPromises.readdir(path[, options])#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
  • withFileTypes<boolean>Default:false
  • recursive<boolean> Iftrue, reads the contents of a directoryrecursively. In recursive mode, it will list all files, sub files, anddirectories.Default:false.
• Returns:<Promise> Fulfills with an array of the names of the files inthe directory excluding'.' and'..'.

Reads the contents of a directory.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe filenames. If theencoding is set to'buffer', the filenames returnedwill be passed as<Buffer> objects.

Ifoptions.withFileTypes is set totrue, the returned array will contain<fs.Dirent> objects.

import { readdir }from'node:fs/promises';try {const files =awaitreaddir(path);for (const fileof files)console.log(file);}catch (err) {console.error(err);}copy

fsPromises.readFile(path[, options])#

• path<string> |<Buffer> |<URL> |<FileHandle> filename orFileHandle
• options<Object> |<string>
  • encoding<string> |<null>Default:null
  • flag<string> Seesupport of file systemflags.Default:'r'.
  • signal<AbortSignal> allows aborting an in-progress readFile
• Returns:<Promise> Fulfills with the contents of the file.

Asynchronously reads the entire contents of a file.

If no encoding is specified (usingoptions.encoding), the data is returnedas a<Buffer> object. Otherwise, the data will be a string.

Ifoptions is a string, then it specifies the encoding.

When thepath is a directory, the behavior offsPromises.readFile() isplatform-specific. On macOS, Linux, and Windows, the promise will be rejectedwith an error. On FreeBSD, a representation of the directory's contents will bereturned.

An example of reading apackage.json file located in the same directory of therunning code:

import { readFile }from'node:fs/promises';try {const filePath =newURL('./package.json',import.meta.url);const contents =awaitreadFile(filePath, {encoding:'utf8' });console.log(contents);}catch (err) {console.error(err.message);}const { readFile } =require('node:fs/promises');const { resolve } =require('node:path');asyncfunctionlogFile() {try {const filePath =resolve('./package.json');const contents =awaitreadFile(filePath, {encoding:'utf8' });console.log(contents);  }catch (err) {console.error(err.message);  }}logFile();copy

It is possible to abort an ongoingreadFile using an<AbortSignal>. If arequest is aborted the promise returned is rejected with anAbortError:

import { readFile }from'node:fs/promises';try {const controller =newAbortController();const { signal } = controller;const promise =readFile(fileName, { signal });// Abort the request before the promise settles.  controller.abort();await promise;}catch (err) {// When a request is aborted - err is an AbortErrorconsole.error(err);}copy

Aborting an ongoing request does not abort individual operatingsystem requests but rather the internal bufferingfs.readFile performs.

Any specified<FileHandle> has to support reading.

fsPromises.readlink(path[, options])#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• Returns:<Promise> Fulfills with thelinkString upon success.

Reads the contents of the symbolic link referred to bypath. See the POSIXreadlink(2) documentation for more detail. The promise is fulfilled with thelinkString upon success.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe link path returned. If theencoding is set to'buffer', the link pathreturned will be passed as a<Buffer> object.

fsPromises.realpath(path[, options])#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• Returns:<Promise> Fulfills with the resolved path upon success.

Determines the actual location ofpath using the same semantics as thefs.realpath.native() function.

Only paths that can be converted to UTF8 strings are supported.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe path. If theencoding is set to'buffer', the path returned will bepassed as a<Buffer> object.

On Linux, when Node.js is linked against musl libc, the procfs file system mustbe mounted on/proc in order for this function to work. Glibc does not havethis restriction.

fsPromises.rename(oldPath, newPath)#

• oldPath<string> |<Buffer> |<URL>
• newPath<string> |<Buffer> |<URL>
• Returns:<Promise> Fulfills withundefined upon success.

RenamesoldPath tonewPath.

fsPromises.rmdir(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • maxRetries<integer> If anEBUSY,EMFILE,ENFILE,ENOTEMPTY, orEPERM error is encountered, Node.js retries the operation with a linearbackoff wait ofretryDelay milliseconds longer on each try. This optionrepresents the number of retries. This option is ignored if therecursiveoption is nottrue.Default:0.
  • recursive<boolean> Iftrue, perform a recursive directory removal. Inrecursive mode, operations are retried on failure.Default:false.Deprecated.
  • retryDelay<integer> The amount of time in milliseconds to wait betweenretries. This option is ignored if therecursive option is nottrue.Default:100.
• Returns:<Promise> Fulfills withundefined upon success.

Removes the directory identified bypath.

UsingfsPromises.rmdir() on a file (not a directory) results in thepromise being rejected with anENOENT error on Windows and anENOTDIRerror on POSIX.

To get a behavior similar to therm -rf Unix command, usefsPromises.rm() with options{ recursive: true, force: true }.

fsPromises.rm(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • force<boolean> Whentrue, exceptions will be ignored ifpath doesnot exist.Default:false.
  • maxRetries<integer> If anEBUSY,EMFILE,ENFILE,ENOTEMPTY, orEPERM error is encountered, Node.js will retry the operation with a linearbackoff wait ofretryDelay milliseconds longer on each try. This optionrepresents the number of retries. This option is ignored if therecursiveoption is nottrue.Default:0.
  • recursive<boolean> Iftrue, perform a recursive directory removal. Inrecursive mode operations are retried on failure.Default:false.
  • retryDelay<integer> The amount of time in milliseconds to wait betweenretries. This option is ignored if therecursive option is nottrue.Default:100.
• Returns:<Promise> Fulfills withundefined upon success.

Removes files and directories (modeled on the standard POSIXrm utility).

fsPromises.stat(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.Stats> object should bebigint.Default:false.
• Returns:<Promise> Fulfills with the<fs.Stats> object for thegivenpath.

fsPromises.statfs(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.StatFs> object should bebigint.Default:false.
• Returns:<Promise> Fulfills with the<fs.StatFs> object for thegivenpath.

fsPromises.symlink(target, path[, type])#

• target<string> |<Buffer> |<URL>
• path<string> |<Buffer> |<URL>
• type<string> |<null>Default:null
• Returns:<Promise> Fulfills withundefined upon success.

Creates a symbolic link.

Thetype argument is only used on Windows platforms and can be one of'dir','file', or'junction'. If thetype argument isnull, Node.js willautodetecttarget type and use'file' or'dir'. If thetarget does notexist,'file' will be used. Windows junction points require the destinationpath to be absolute. When using'junction', thetarget argument willautomatically be normalized to absolute path. Junction points on NTFS volumescan only point to directories.

fsPromises.truncate(path[, len])#

• path<string> |<Buffer> |<URL>
• len<integer>Default:0
• Returns:<Promise> Fulfills withundefined upon success.

Truncates (shortens or extends the length) of the content atpath tolenbytes.

fsPromises.unlink(path)#

• path<string> |<Buffer> |<URL>
• Returns:<Promise> Fulfills withundefined upon success.

Ifpath refers to a symbolic link, then the link is removed without affectingthe file or directory to which that link refers. If thepath refers to a filepath that is not a symbolic link, the file is deleted. See the POSIXunlink(2)documentation for more detail.

fsPromises.utimes(path, atime, mtime)#

• path<string> |<Buffer> |<URL>
• atime<number> |<string> |<Date>
• mtime<number> |<string> |<Date>
• Returns:<Promise> Fulfills withundefined upon success.

Change the file system timestamps of the object referenced bypath.

Theatime andmtime arguments follow these rules:

• Values can be either numbers representing Unix epoch time,Dates, or anumeric string like'123456789.0'.
• If the value can not be converted to a number, or isNaN,Infinity, or-Infinity, anError will be thrown.

fsPromises.watch(filename[, options])#

• filename<string> |<Buffer> |<URL>
• options<string> |<Object>
  • persistent<boolean> Indicates whether the process should continue to runas long as files are being watched.Default:true.
  • recursive<boolean> Indicates whether all subdirectories should bewatched, or only the current directory. This applies when a directory isspecified, and only on supported platforms (Seecaveats).Default:false.
  • encoding<string> Specifies the character encoding to be used for thefilename passed to the listener.Default:'utf8'.
  • signal<AbortSignal> An<AbortSignal> used to signal when the watchershould stop.
  • maxQueue<number> Specifies the number of events to queue between iterationsof the<AsyncIterator> returned.Default:2048.
  • overflow<string> Either'ignore' or'throw' when there are more events to bequeued thanmaxQueue allows.'ignore' means overflow events are dropped and awarning is emitted, while'throw' means to throw an exception.Default:'ignore'.
• Returns:<AsyncIterator> of objects with the properties:
  • eventType<string> The type of change
  • filename<string> |<Buffer> |<null> The name of the file changed.

Returns an async iterator that watches for changes onfilename, wherefilenameis either a file or a directory.

const { watch } =require('node:fs/promises');const ac =newAbortController();const { signal } = ac;setTimeout(() => ac.abort(),10000);(async () => {try {const watcher =watch(__filename, { signal });forawait (const eventof watcher)console.log(event);  }catch (err) {if (err.name ==='AbortError')return;throw err;  }})();copy

On most platforms,'rename' is emitted whenever a filename appears ordisappears in the directory.

All thecaveats forfs.watch() also apply tofsPromises.watch().

fsPromises.writeFile(file, data[, options])#

• file<string> |<Buffer> |<URL> |<FileHandle> filename orFileHandle
• data<string> |<Buffer> |<TypedArray> |<DataView> |<AsyncIterable> |<Iterable> |<Stream>
• options<Object> |<string>
  • encoding<string> |<null>Default:'utf8'
  • mode<integer>Default:0o666
  • flag<string> Seesupport of file systemflags.Default:'w'.
  • flush<boolean> If all data is successfully written to the file, andflush istrue,filehandle.sync() is used to flush the data.Default:false.
  • signal<AbortSignal> allows aborting an in-progress writeFile
• Returns:<Promise> Fulfills withundefined upon success.

Asynchronously writes data to a file, replacing the file if it already exists.data can be a string, a buffer, an<AsyncIterable>, or an<Iterable> object.

Theencoding option is ignored ifdata is a buffer.

Ifoptions is a string, then it specifies the encoding.

Themode option only affects the newly created file. Seefs.open()for more details.

Any specified<FileHandle> has to support writing.

It is unsafe to usefsPromises.writeFile() multiple times on the same filewithout waiting for the promise to be settled.

Similarly tofsPromises.readFile -fsPromises.writeFile is a conveniencemethod that performs multiplewrite calls internally to write the bufferpassed to it. For performance sensitive code consider usingfs.createWriteStream() orfilehandle.createWriteStream().

It is possible to use an<AbortSignal> to cancel anfsPromises.writeFile().Cancelation is "best effort", and some amount of data is likely stillto be written.

import { writeFile }from'node:fs/promises';import {Buffer }from'node:buffer';try {const controller =newAbortController();const { signal } = controller;const data =newUint8Array(Buffer.from('Hello Node.js'));const promise =writeFile('message.txt', data, { signal });// Abort the request before the promise settles.  controller.abort();await promise;}catch (err) {// When a request is aborted - err is an AbortErrorconsole.error(err);}copy

Aborting an ongoing request does not abort individual operatingsystem requests but rather the internal bufferingfs.writeFile performs.

fsPromises.constants#

• Type:<Object>

Returns an object containing commonly used constants for file systemoperations. The object is the same asfs.constants. SeeFS constantsfor more details.

fs.access(path[, mode], callback)#

• path<string> |<Buffer> |<URL>
• mode<integer>Default:fs.constants.F_OK
• callback<Function>
  • err<Error>

Tests a user's permissions for the file or directory specified bypath.Themode argument is an optional integer that specifies the accessibilitychecks to be performed.mode should be either the valuefs.constants.F_OKor a mask consisting of the bitwise OR of any offs.constants.R_OK,fs.constants.W_OK, andfs.constants.X_OK (e.g.fs.constants.W_OK | fs.constants.R_OK). CheckFile access constants forpossible values ofmode.

The final argument,callback, is a callback function that is invoked witha possible error argument. If any of the accessibility checks fail, the errorargument will be anError object. The following examples check ifpackage.json exists, and if it is readable or writable.

import { access, constants }from'node:fs';const file ='package.json';// Check if the file exists in the current directory.access(file, constants.F_OK,(err) => {console.log(`${file}${err ?'does not exist' :'exists'}`);});// Check if the file is readable.access(file, constants.R_OK,(err) => {console.log(`${file}${err ?'is not readable' :'is readable'}`);});// Check if the file is writable.access(file, constants.W_OK,(err) => {console.log(`${file}${err ?'is not writable' :'is writable'}`);});// Check if the file is readable and writable.access(file, constants.R_OK | constants.W_OK,(err) => {console.log(`${file}${err ?'is not' :'is'} readable and writable`);});copy

Do not usefs.access() to check for the accessibility of a file before callingfs.open(),fs.readFile(), orfs.writeFile(). Doingso introduces a race condition, since other processes may change the file'sstate between the two calls. Instead, user code should open/read/write thefile directly and handle the error raised if the file is not accessible.

write (NOT RECOMMENDED)

import { access, open, close }from'node:fs';access('myfile',(err) => {if (!err) {console.error('myfile already exists');return;  }open('myfile','wx',(err, fd) => {if (err)throw err;try {writeMyData(fd);    }finally {close(fd,(err) => {if (err)throw err;      });    }  });});copy

write (RECOMMENDED)

import { open, close }from'node:fs';open('myfile','wx',(err, fd) => {if (err) {if (err.code ==='EEXIST') {console.error('myfile already exists');return;    }throw err;  }try {writeMyData(fd);  }finally {close(fd,(err) => {if (err)throw err;    });  }});copy

read (NOT RECOMMENDED)

import { access, open, close }from'node:fs';access('myfile',(err) => {if (err) {if (err.code ==='ENOENT') {console.error('myfile does not exist');return;    }throw err;  }open('myfile','r',(err, fd) => {if (err)throw err;try {readMyData(fd);    }finally {close(fd,(err) => {if (err)throw err;      });    }  });});copy

read (RECOMMENDED)

import { open, close }from'node:fs';open('myfile','r',(err, fd) => {if (err) {if (err.code ==='ENOENT') {console.error('myfile does not exist');return;    }throw err;  }try {readMyData(fd);  }finally {close(fd,(err) => {if (err)throw err;    });  }});copy

The "not recommended" examples above check for accessibility and then use thefile; the "recommended" examples are better because they use the file directlyand handle the error, if any.

In general, check for the accessibility of a file only if the file will not beused directly, for example when its accessibility is a signal from anotherprocess.

On Windows, access-control policies (ACLs) on a directory may limit access toa file or directory. Thefs.access() function, however, does not check theACL and therefore may report that a path is accessible even if the ACL restrictsthe user from reading or writing to it.

fs.appendFile(path, data[, options], callback)#

• path<string> |<Buffer> |<URL> |<number> filename or file descriptor
• data<string> |<Buffer>
• options<Object> |<string>
  • encoding<string> |<null>Default:'utf8'
  • mode<integer>Default:0o666
  • flag<string> Seesupport of file systemflags.Default:'a'.
  • flush<boolean> Iftrue, the underlying file descriptor is flushedprior to closing it.Default:false.
• callback<Function>
  • err<Error>

Asynchronously append data to a file, creating the file if it does not yetexist.data can be a string or a<Buffer>.

Themode option only affects the newly created file. Seefs.open()for more details.

import { appendFile }from'node:fs';appendFile('message.txt','data to append',(err) => {if (err)throw err;console.log('The "data to append" was appended to file!');});copy

Ifoptions is a string, then it specifies the encoding:

import { appendFile }from'node:fs';appendFile('message.txt','data to append','utf8', callback);copy

Thepath may be specified as a numeric file descriptor that has been openedfor appending (usingfs.open() orfs.openSync()). The file descriptor willnot be closed automatically.

import { open, close, appendFile }from'node:fs';functioncloseFd(fd) {close(fd,(err) => {if (err)throw err;  });}open('message.txt','a',(err, fd) => {if (err)throw err;try {appendFile(fd,'data to append','utf8',(err) => {closeFd(fd);if (err)throw err;    });  }catch (err) {closeFd(fd);throw err;  }});copy

fs.chmod(path, mode, callback)#

• path<string> |<Buffer> |<URL>
• mode<string> |<integer>
• callback<Function>
  • err<Error>

Asynchronously changes the permissions of a file. No arguments other than apossible exception are given to the completion callback.

See the POSIXchmod(2) documentation for more detail.

import { chmod }from'node:fs';chmod('my_file.txt',0o775,(err) => {if (err)throw err;console.log('The permissions for file "my_file.txt" have been changed!');});copy

fs.chown(path, uid, gid, callback)#

• path<string> |<Buffer> |<URL>
• uid<integer>
• gid<integer>
• callback<Function>
  • err<Error>

Asynchronously changes owner and group of a file. No arguments other than apossible exception are given to the completion callback.

See the POSIXchown(2) documentation for more detail.

fs.close(fd[, callback])#

• fd<integer>
• callback<Function>
  • err<Error>

Closes the file descriptor. No arguments other than a possible exception aregiven to the completion callback.

Callingfs.close() on any file descriptor (fd) that is currently in usethrough any otherfs operation may lead to undefined behavior.

See the POSIXclose(2) documentation for more detail.

fs.copyFile(src, dest[, mode], callback)#

• src<string> |<Buffer> |<URL> source filename to copy
• dest<string> |<Buffer> |<URL> destination filename of the copy operation
• mode<integer> modifiers for copy operation.Default:0.
• callback<Function>
  • err<Error>

Asynchronously copiessrc todest. By default,dest is overwritten if italready exists. No arguments other than a possible exception are given to thecallback function. Node.js makes no guarantees about the atomicity of the copyoperation. If an error occurs after the destination file has been opened forwriting, Node.js will attempt to remove the destination.

mode is an optional integer that specifies the behaviorof the copy operation. It is possible to create a mask consisting of the bitwiseOR of two or more values (e.g.fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: The copy operation will fail ifdest alreadyexists.
• fs.constants.COPYFILE_FICLONE: The copy operation will attempt to create acopy-on-write reflink. If the platform does not support copy-on-write, then afallback copy mechanism is used.
• fs.constants.COPYFILE_FICLONE_FORCE: The copy operation will attempt tocreate a copy-on-write reflink. If the platform does not supportcopy-on-write, then the operation will fail.

import { copyFile, constants }from'node:fs';functioncallback(err) {if (err)throw err;console.log('source.txt was copied to destination.txt');}// destination.txt will be created or overwritten by default.copyFile('source.txt','destination.txt', callback);// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.copyFile('source.txt','destination.txt', constants.COPYFILE_EXCL, callback);copy

fs.cp(src, dest[, options], callback)#

• src<string> |<URL> source path to copy.
• dest<string> |<URL> destination path to copy to.
• options<Object>
  • dereference<boolean> dereference symlinks.Default:false.
  • errorOnExist<boolean> whenforce isfalse, and the destinationexists, throw an error.Default:false.
  • filter<Function> Function to filter copied files/directories. Returntrue to copy the item,false to ignore it. When ignoring a directory,all of its contents will be skipped as well. Can also return aPromisethat resolves totrue orfalseDefault:undefined.
    • src<string> source path to copy.
    • dest<string> destination path to copy to.
    • Returns:<boolean> |<Promise> A value that is coercible toboolean oraPromise that fulfils with such value.
  • force<boolean> overwrite existing file or directory. The copyoperation will ignore errors if you set this to false and the destinationexists. Use theerrorOnExist option to change this behavior.Default:true.
  • mode<integer> modifiers for copy operation.Default:0.Seemode flag offs.copyFile().
  • preserveTimestamps<boolean> Whentrue timestamps fromsrc willbe preserved.Default:false.
  • recursive<boolean> copy directories recursivelyDefault:false
  • verbatimSymlinks<boolean> Whentrue, path resolution for symlinks willbe skipped.Default:false
• callback<Function>
  • err<Error>

Asynchronously copies the entire directory structure fromsrc todest,including subdirectories and files.

When copying a directory to another directory, globs are not supported andbehavior is similar tocp dir1/ dir2/.

fs.createReadStream(path[, options])#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • flags<string> Seesupport of file systemflags.Default:'r'.
  • encoding<string>Default:null
  • fd<integer> |<FileHandle>Default:null
  • mode<integer>Default:0o666
  • autoClose<boolean>Default:true
  • emitClose<boolean>Default:true
  • start<integer>
  • end<integer>Default:Infinity
  • highWaterMark<integer>Default:64 * 1024
  • fs<Object> |<null>Default:null
  • signal<AbortSignal> |<null>Default:null
• Returns:<fs.ReadStream>

options can includestart andend values to read a range of bytes fromthe file instead of the entire file. Bothstart andend are inclusive andstart counting at 0, allowed values are in the[0,Number.MAX_SAFE_INTEGER] range. Iffd is specified andstart isomitted orundefined,fs.createReadStream() reads sequentially from thecurrent file position. Theencoding can be any one of those accepted by<Buffer>.

Iffd is specified,ReadStream will ignore thepath argument and will usethe specified file descriptor. This means that no'open' event will beemitted.fd should be blocking; non-blockingfds should be passed to<net.Socket>.

Iffd points to a character device that only supports blocking reads(such as keyboard or sound card), read operations do not finish until data isavailable. This can prevent the process from exiting and the stream fromclosing naturally.

By default, the stream will emit a'close' event after it has beendestroyed. Set theemitClose option tofalse to change this behavior.

By providing thefs option, it is possible to override the correspondingfsimplementations foropen,read, andclose. When providing thefs option,an override forread is required. If nofd is provided, an override foropen is also required. IfautoClose istrue, an override forclose isalso required.

import { createReadStream }from'node:fs';// Create a stream from some character device.const stream =createReadStream('/dev/input/event0');setTimeout(() => {  stream.close();// This may not close the stream.// Artificially marking end-of-stream, as if the underlying resource had// indicated end-of-file by itself, allows the stream to close.// This does not cancel pending read operations, and if there is such an// operation, the process may still not be able to exit successfully// until it finishes.  stream.push(null);  stream.read(0);},100);copy

IfautoClose is false, then the file descriptor won't be closed, even ifthere's an error. It is the application's responsibility to close it and makesure there's no file descriptor leak. IfautoClose is set to true (defaultbehavior), on'error' or'end' the file descriptor will be closedautomatically.

mode sets the file mode (permission and sticky bits), but only if thefile was created.

An example to read the last 10 bytes of a file which is 100 bytes long:

import { createReadStream }from'node:fs';createReadStream('sample.txt', {start:90,end:99 });copy

Ifoptions is a string, then it specifies the encoding.

fs.createWriteStream(path[, options])#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • flags<string> Seesupport of file systemflags.Default:'w'.
  • encoding<string>Default:'utf8'
  • fd<integer> |<FileHandle>Default:null
  • mode<integer>Default:0o666
  • autoClose<boolean>Default:true
  • emitClose<boolean>Default:true
  • start<integer>
  • fs<Object> |<null>Default:null
  • signal<AbortSignal> |<null>Default:null
  • highWaterMark<number>Default:16384
  • flush<boolean> Iftrue, the underlying file descriptor is flushedprior to closing it.Default:false.
• Returns:<fs.WriteStream>

options may also include astart option to allow writing data at someposition past the beginning of the file, allowed values are in the[0,Number.MAX_SAFE_INTEGER] range. Modifying a file rather thanreplacing it may require theflags option to be set tor+ rather than thedefaultw. Theencoding can be any one of those accepted by<Buffer>.

IfautoClose is set to true (default behavior) on'error' or'finish'the file descriptor will be closed automatically. IfautoClose is false,then the file descriptor won't be closed, even if there's an error.It is the application's responsibility to close it and make sure there's nofile descriptor leak.

By default, the stream will emit a'close' event after it has beendestroyed. Set theemitClose option tofalse to change this behavior.

By providing thefs option it is possible to override the correspondingfsimplementations foropen,write,writev, andclose. Overridingwrite()withoutwritev() can reduce performance as some optimizations (_writev())will be disabled. When providing thefs option, overrides for at least one ofwrite andwritev are required. If nofd option is supplied, an overrideforopen is also required. IfautoClose istrue, an override forcloseis also required.

Like<fs.ReadStream>, iffd is specified,<fs.WriteStream> will ignore thepath argument and will use the specified file descriptor. This means that no'open' event will be emitted.fd should be blocking; non-blockingfdsshould be passed to<net.Socket>.

Ifoptions is a string, then it specifies the encoding.

fs.exists(path, callback)#

• path<string> |<Buffer> |<URL>
• callback<Function>
  • exists<boolean>

Test whether or not the element at the givenpath exists by checking with the file system.Then call thecallback argument with either true or false:

import { exists }from'node:fs';exists('/etc/passwd',(e) => {console.log(e ?'it exists' :'no passwd!');});copy

The parameters for this callback are not consistent with other Node.jscallbacks. Normally, the first parameter to a Node.js callback is anerrparameter, optionally followed by other parameters. Thefs.exists() callbackhas only one boolean parameter. This is one reasonfs.access() is recommendedinstead offs.exists().

Ifpath is a symbolic link, it is followed. Thus, ifpath exists but pointsto a non-existent element, the callback will receive the valuefalse.

Usingfs.exists() to check for the existence of a file before callingfs.open(),fs.readFile(), orfs.writeFile() is not recommended. Doingso introduces a race condition, since other processes may change the file'sstate between the two calls. Instead, user code should open/read/write thefile directly and handle the error raised if the file does not exist.

write (NOT RECOMMENDED)

import { exists, open, close }from'node:fs';exists('myfile',(e) => {if (e) {console.error('myfile already exists');  }else {open('myfile','wx',(err, fd) => {if (err)throw err;try {writeMyData(fd);      }finally {close(fd,(err) => {if (err)throw err;        });      }    });  }});copy

write (RECOMMENDED)

import { open, close }from'node:fs';open('myfile','wx',(err, fd) => {if (err) {if (err.code ==='EEXIST') {console.error('myfile already exists');return;    }throw err;  }try {writeMyData(fd);  }finally {close(fd,(err) => {if (err)throw err;    });  }});copy

read (NOT RECOMMENDED)

import { open, close, exists }from'node:fs';exists('myfile',(e) => {if (e) {open('myfile','r',(err, fd) => {if (err)throw err;try {readMyData(fd);      }finally {close(fd,(err) => {if (err)throw err;        });      }    });  }else {console.error('myfile does not exist');  }});copy

read (RECOMMENDED)

import { open, close }from'node:fs';open('myfile','r',(err, fd) => {if (err) {if (err.code ==='ENOENT') {console.error('myfile does not exist');return;    }throw err;  }try {readMyData(fd);  }finally {close(fd,(err) => {if (err)throw err;    });  }});copy

The "not recommended" examples above check for existence and then use thefile; the "recommended" examples are better because they use the file directlyand handle the error, if any.

In general, check for the existence of a file only if the file won't beused directly, for example when its existence is a signal from anotherprocess.

fs.fchmod(fd, mode, callback)#

• fd<integer>
• mode<string> |<integer>
• callback<Function>
  • err<Error>

Sets the permissions on the file. No arguments other than a possible exceptionare given to the completion callback.

See the POSIXfchmod(2) documentation for more detail.

fs.fchown(fd, uid, gid, callback)#

• fd<integer>
• uid<integer>
• gid<integer>
• callback<Function>
  • err<Error>

Sets the owner of the file. No arguments other than a possible exception aregiven to the completion callback.

See the POSIXfchown(2) documentation for more detail.

fs.fdatasync(fd, callback)#

• fd<integer>
• callback<Function>
  • err<Error>

Forces all currently queued I/O operations associated with the file to theoperating system's synchronized I/O completion state. Refer to the POSIXfdatasync(2) documentation for details. No arguments other than a possibleexception are given to the completion callback.

fs.fstat(fd[, options], callback)#

• fd<integer>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.Stats> object should bebigint.Default:false.
• callback<Function>
  • err<Error>
  • stats<fs.Stats>

Invokes the callback with the<fs.Stats> for the file descriptor.

See the POSIXfstat(2) documentation for more detail.

fs.fsync(fd, callback)#

• fd<integer>
• callback<Function>
  • err<Error>

Request that all data for the open file descriptor is flushed to the storagedevice. The specific implementation is operating system and device specific.Refer to the POSIXfsync(2) documentation for more detail. No arguments otherthan a possible exception are given to the completion callback.

fs.ftruncate(fd[, len], callback)#

• fd<integer>
• len<integer>Default:0
• callback<Function>
  • err<Error>

Truncates the file descriptor. No arguments other than a possible exception aregiven to the completion callback.

See the POSIXftruncate(2) documentation for more detail.

If the file referred to by the file descriptor was larger thanlen bytes, onlythe firstlen bytes will be retained in the file.

For example, the following program retains only the first four bytes of thefile:

import { open, close, ftruncate }from'node:fs';functioncloseFd(fd) {close(fd,(err) => {if (err)throw err;  });}open('temp.txt','r+',(err, fd) => {if (err)throw err;try {ftruncate(fd,4,(err) => {closeFd(fd);if (err)throw err;    });  }catch (err) {closeFd(fd);if (err)throw err;  }});copy

If the file previously was shorter thanlen bytes, it is extended, and theextended part is filled with null bytes ('\0'):

Iflen is negative then0 will be used.

fs.futimes(fd, atime, mtime, callback)#

• fd<integer>
• atime<number> |<string> |<Date>
• mtime<number> |<string> |<Date>
• callback<Function>
  • err<Error>

Change the file system timestamps of the object referenced by the supplied filedescriptor. Seefs.utimes().

fs.glob(pattern[, options], callback)#

• pattern<string> |<string[]>

• options<Object>

  • cwd<string> |<URL> current working directory.Default:process.cwd()
  • exclude<Function> |<string[]> Function to filter out files/directories or alist of glob patterns to be excluded. If a function is provided, returntrue to exclude the item,false to include it.Default:undefined.
  • withFileTypes<boolean>true if the glob should return paths as Dirents,false otherwise.Default:false.

• callback<Function>

  • err<Error>

• Retrieves the files matching the specified pattern.

import { glob }from'node:fs';glob('**/*.js',(err, matches) => {if (err)throw err;console.log(matches);});const { glob } =require('node:fs');glob('**/*.js',(err, matches) => {if (err)throw err;console.log(matches);});copy

fs.lchmod(path, mode, callback)#

• path<string> |<Buffer> |<URL>
• mode<integer>
• callback<Function>
  • err<Error> |<AggregateError>

Changes the permissions on a symbolic link. No arguments other than a possibleexception are given to the completion callback.

This method is only implemented on macOS.

See the POSIXlchmod(2) documentation for more detail.

fs.lchown(path, uid, gid, callback)#

• path<string> |<Buffer> |<URL>
• uid<integer>
• gid<integer>
• callback<Function>
  • err<Error>

Set the owner of the symbolic link. No arguments other than a possibleexception are given to the completion callback.

See the POSIXlchown(2) documentation for more detail.

fs.lutimes(path, atime, mtime, callback)#

• path<string> |<Buffer> |<URL>
• atime<number> |<string> |<Date>
• mtime<number> |<string> |<Date>
• callback<Function>
  • err<Error>

Changes the access and modification times of a file in the same way asfs.utimes(), with the difference that if the path refers to a symboliclink, then the link is not dereferenced: instead, the timestamps of thesymbolic link itself are changed.

No arguments other than a possible exception are given to the completioncallback.

fs.link(existingPath, newPath, callback)#

• existingPath<string> |<Buffer> |<URL>
• newPath<string> |<Buffer> |<URL>
• callback<Function>
  • err<Error>

Creates a new link from theexistingPath to thenewPath. See the POSIXlink(2) documentation for more detail. No arguments other than a possibleexception are given to the completion callback.

fs.lstat(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.Stats> object should bebigint.Default:false.
• callback<Function>
  • err<Error>
  • stats<fs.Stats>

Retrieves the<fs.Stats> for the symbolic link referred to by the path.The callback gets two arguments(err, stats) wherestats is a<fs.Stats>object.lstat() is identical tostat(), except that ifpath is a symboliclink, then the link itself is stat-ed, not the file that it refers to.

See the POSIXlstat(2) documentation for more details.

fs.mkdir(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object> |<integer>
  • recursive<boolean>Default:false
  • mode<string> |<integer> Not supported on Windows.Default:0o777.
• callback<Function>
  • err<Error>
  • path<string> |<undefined> Present only if a directory is created withrecursive set totrue.

Asynchronously creates a directory.

The callback is given a possible exception and, ifrecursive istrue, thefirst directory path created,(err[, path]).path can still beundefined whenrecursive istrue, if no directory wascreated (for instance, if it was previously created).

The optionaloptions argument can be an integer specifyingmode (permissionand sticky bits), or an object with amode property and arecursiveproperty indicating whether parent directories should be created. Callingfs.mkdir() whenpath is a directory that exists results in an error onlywhenrecursive is false. Ifrecursive is false and the directory exists,anEEXIST error occurs.

import { mkdir }from'node:fs';// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.mkdir('./tmp/a/apple', {recursive:true },(err) => {if (err)throw err;});copy

On Windows, usingfs.mkdir() on the root directory even with recursion willresult in an error:

import { mkdir }from'node:fs';mkdir('/', {recursive:true },(err) => {// => [Error: EPERM: operation not permitted, mkdir 'C:\']});copy

See the POSIXmkdir(2) documentation for more details.

fs.mkdtemp(prefix[, options], callback)#

• prefix<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• callback<Function>
  • err<Error>
  • directory<string>

Creates a unique temporary directory.

Generates six random characters to be appended behind a requiredprefix to create a unique temporary directory. Due to platforminconsistencies, avoid trailingX characters inprefix. Some platforms,notably the BSDs, can return more than six random characters, and replacetrailingX characters inprefix with random characters.

The created directory path is passed as a string to the callback's secondparameter.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use.

import { mkdtemp }from'node:fs';import { join }from'node:path';import { tmpdir }from'node:os';mkdtemp(join(tmpdir(),'foo-'),(err, directory) => {if (err)throw err;console.log(directory);// Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2});copy

Thefs.mkdtemp() method will append the six randomly selected charactersdirectly to theprefix string. For instance, given a directory/tmp, if theintention is to create a temporary directorywithin/tmp, theprefixmust end with a trailing platform-specific path separator(require('node:path').sep).

import { tmpdir }from'node:os';import { mkdtemp }from'node:fs';// The parent directory for the new temporary directoryconst tmpDir =tmpdir();// This method is *INCORRECT*:mkdtemp(tmpDir,(err, directory) => {if (err)throw err;console.log(directory);// Will print something similar to `/tmpabc123`.// A new temporary directory is created at the file system root// rather than *within* the /tmp directory.});// This method is *CORRECT*:import { sep }from'node:path';mkdtemp(`${tmpDir}${sep}`,(err, directory) => {if (err)throw err;console.log(directory);// Will print something similar to `/tmp/abc123`.// A new temporary directory is created within// the /tmp directory.});copy

fs.open(path[, flags[, mode]], callback)#

• path<string> |<Buffer> |<URL>
• flags<string> |<number> Seesupport of file systemflags.Default:'r'.
• mode<string> |<integer>Default:0o666 (readable and writable)
• callback<Function>
  • err<Error>
  • fd<integer>

Asynchronous file open. See the POSIXopen(2) documentation for more details.

mode sets the file mode (permission and sticky bits), but only if the file wascreated. On Windows, only the write permission can be manipulated; seefs.chmod().

The callback gets two arguments(err, fd).

Some characters (< > : " / \ | ? *) are reserved under Windows as documentedbyNaming Files, Paths, and Namespaces. Under NTFS, if the filename containsa colon, Node.js will open a file system stream, as described bythis MSDN page.

Functions based onfs.open() exhibit this behavior as well:fs.writeFile(),fs.readFile(), etc.

fs.openAsBlob(path[, options])#

• path<string> |<Buffer> |<URL>
• options<Object>
  • type<string> An optional mime type for the blob.
• Returns:<Promise> Fulfills with a<Blob> upon success.

Returns a<Blob> whose data is backed by the given file.

The file must not be modified after the<Blob> is created. Any modificationswill cause reading the<Blob> data to fail with aDOMException error.Synchronous stat operations on the file when theBlob is created, and beforeeach read in order to detect whether the file data has been modified on disk.

import { openAsBlob }from'node:fs';const blob =awaitopenAsBlob('the.file.txt');const ab =await blob.arrayBuffer();blob.stream();const { openAsBlob } =require('node:fs');(async () => {const blob =awaitopenAsBlob('the.file.txt');const ab =await blob.arrayBuffer();  blob.stream();})();copy

fs.opendir(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object>
  • encoding<string> |<null>Default:'utf8'
  • bufferSize<number> Number of directory entries that are bufferedinternally when reading from the directory. Higher values lead to betterperformance but higher memory usage.Default:32
  • recursive<boolean>Default:false
• callback<Function>
  • err<Error>
  • dir<fs.Dir>

Asynchronously open a directory. See the POSIXopendir(3) documentation formore details.

Creates an<fs.Dir>, which contains all further functions for reading fromand cleaning up the directory.

Theencoding option sets the encoding for thepath while opening thedirectory and subsequent read operations.

fs.read(fd, buffer, offset, length, position, callback)#

• fd<integer>
• buffer<Buffer> |<TypedArray> |<DataView> The buffer that the data will bewritten to.
• offset<integer> The position inbuffer to write the data to.
• length<integer> The number of bytes to read.
• position<integer> |<bigint> |<null> Specifies where to begin reading from in thefile. Ifposition isnull or-1, data will be read from the currentfile position, and the file position will be updated. Ifposition isa non-negative integer, the file position will be unchanged.
• callback<Function>
  • err<Error>
  • bytesRead<integer>
  • buffer<Buffer>

Read data from the file specified byfd.

The callback is given the three arguments,(err, bytesRead, buffer).

If the file is not modified concurrently, the end-of-file is reached when thenumber of bytes read is zero.

If this method is invoked as itsutil.promisify()ed version, it returnsa promise for anObject withbytesRead andbuffer properties.

Thefs.read() method reads data from the file specifiedby the file descriptor (fd).Thelength argument indicates the maximum numberof bytes that Node.jswill attempt to read from the kernel.However, the actual number of bytes read (bytesRead) can be lowerthan the specifiedlength for various reasons.

For example:

• If the file is shorter than the specifiedlength,bytesReadwill be set to the actual number of bytes read.
• If the file encounters EOF (End of File) before the buffer couldbe filled, Node.js will read all available bytes until EOF is encountered,and thebytesRead parameter in the callback will indicatethe actual number of bytes read, which may be less than the specifiedlength.
• If the file is on a slow networkfilesystemor encounters any other issue during reading,bytesRead can be lower than the specifiedlength.

Therefore, when usingfs.read(), it's important tocheck thebytesRead value todetermine how many bytes were actually read from the file.Depending on your applicationlogic, you may need to handle cases wherebytesReadis lower than the specifiedlength,such as by wrapping the read call in a loop if you requirea minimum amount of bytes.

This behavior is similar to the POSIXpreadv2 function.

fs.read(fd[, options], callback)#

• fd<integer>
• options<Object>
  • buffer<Buffer> |<TypedArray> |<DataView>Default:Buffer.alloc(16384)
  • offset<integer>Default:0
  • length<integer>Default:buffer.byteLength - offset
  • position<integer> |<bigint> |<null>Default:null
• callback<Function>
  • err<Error>
  • bytesRead<integer>
  • buffer<Buffer>

Similar to thefs.read() function, this version takes an optionaloptions object. If nooptions object is specified, it will default with theabove values.

fs.read(fd, buffer[, options], callback)#

• fd<integer>
• buffer<Buffer> |<TypedArray> |<DataView> The buffer that the data will bewritten to.
• options<Object>
  • offset<integer>Default:0
  • length<integer>Default:buffer.byteLength - offset
  • position<integer> |<bigint>Default:null
• callback<Function>
  • err<Error>
  • bytesRead<integer>
  • buffer<Buffer>

Similar to thefs.read() function, this version takes an optionaloptions object. If nooptions object is specified, it will default with theabove values.

fs.readdir(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
  • withFileTypes<boolean>Default:false
  • recursive<boolean> Iftrue, reads the contents of a directoryrecursively. In recursive mode, it will list all files, sub files anddirectories.Default:false.
• callback<Function>
  • err<Error>
  • files<string[]> |<Buffer[]> |<fs.Dirent[]>

Reads the contents of a directory. The callback gets two arguments(err, files)wherefiles is an array of the names of the files in the directory excluding'.' and'..'.

See the POSIXreaddir(3) documentation for more details.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe filenames passed to the callback. If theencoding is set to'buffer',the filenames returned will be passed as<Buffer> objects.

Ifoptions.withFileTypes is set totrue, thefiles array will contain<fs.Dirent> objects.

fs.readFile(path[, options], callback)#

• path<string> |<Buffer> |<URL> |<integer> filename or file descriptor
• options<Object> |<string>
  • encoding<string> |<null>Default:null
  • flag<string> Seesupport of file systemflags.Default:'r'.
  • signal<AbortSignal> allows aborting an in-progress readFile
• callback<Function>
  • err<Error> |<AggregateError>
  • data<string> |<Buffer>

Asynchronously reads the entire contents of a file.

import { readFile }from'node:fs';readFile('/etc/passwd',(err, data) => {if (err)throw err;console.log(data);});copy

The callback is passed two arguments(err, data), wheredata is thecontents of the file.

If no encoding is specified, then the raw buffer is returned.

Ifoptions is a string, then it specifies the encoding:

import { readFile }from'node:fs';readFile('/etc/passwd','utf8', callback);copy

When the path is a directory, the behavior offs.readFile() andfs.readFileSync() is platform-specific. On macOS, Linux, and Windows, anerror will be returned. On FreeBSD, a representation of the directory's contentswill be returned.

import { readFile }from'node:fs';// macOS, Linux, and WindowsreadFile('<directory>',(err, data) => {// => [Error: EISDIR: illegal operation on a directory, read <directory>]});//  FreeBSDreadFile('<directory>',(err, data) => {// => null, <data>});copy

It is possible to abort an ongoing request using anAbortSignal. If arequest is aborted the callback is called with anAbortError:

import { readFile }from'node:fs';const controller =newAbortController();const signal = controller.signal;readFile(fileInfo[0].name, { signal },(err, buf) => {// ...});// When you want to abort the requestcontroller.abort();copy

Thefs.readFile() function buffers the entire file. To minimize memory costs,when possible prefer streaming viafs.createReadStream().

Aborting an ongoing request does not abort individual operatingsystem requests but rather the internal bufferingfs.readFile performs.

fs.readlink(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• callback<Function>
  • err<Error>
  • linkString<string> |<Buffer>

Reads the contents of the symbolic link referred to bypath. The callback getstwo arguments(err, linkString).

See the POSIXreadlink(2) documentation for more details.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe link path passed to the callback. If theencoding is set to'buffer',the link path returned will be passed as a<Buffer> object.

fs.readv(fd, buffers[, position], callback)#

• fd<integer>
• buffers<ArrayBufferView[]>
• position<integer> |<null>Default:null
• callback<Function>
  • err<Error>
  • bytesRead<integer>
  • buffers<ArrayBufferView[]>

Read from a file specified byfd and write to an array ofArrayBufferViewsusingreadv().

position is the offset from the beginning of the file from where datashould be read. Iftypeof position !== 'number', the data will be readfrom the current position.

The callback will be given three arguments:err,bytesRead, andbuffers.bytesRead is how many bytes were read from the file.

If this method is invoked as itsutil.promisify()ed version, it returnsa promise for anObject withbytesRead andbuffers properties.

fs.realpath(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• callback<Function>
  • err<Error>
  • resolvedPath<string> |<Buffer>

Asynchronously computes the canonical pathname by resolving.,.., andsymbolic links.

A canonical pathname is not necessarily unique. Hard links and bind mounts canexpose a file system entity through many pathnames.

This function behaves likerealpath(3), with some exceptions:

1. No case conversion is performed on case-insensitive file systems.

2. The maximum number of symbolic links is platform-independent and generally(much) higher than what the nativerealpath(3) implementation supports.

Thecallback gets two arguments(err, resolvedPath). May useprocess.cwdto resolve relative paths.

Only paths that can be converted to UTF8 strings are supported.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe path passed to the callback. If theencoding is set to'buffer',the path returned will be passed as a<Buffer> object.

Ifpath resolves to a socket or a pipe, the function will return a systemdependent name for that object.

A path that does not exist results in an ENOENT error.error.path is the absolute file path.

fs.realpath.native(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<string> |<Object>
  • encoding<string>Default:'utf8'
• callback<Function>
  • err<Error>
  • resolvedPath<string> |<Buffer>

Asynchronousrealpath(3).

Thecallback gets two arguments(err, resolvedPath).

Only paths that can be converted to UTF8 strings are supported.

The optionaloptions argument can be a string specifying an encoding, or anobject with anencoding property specifying the character encoding to use forthe path passed to the callback. If theencoding is set to'buffer',the path returned will be passed as a<Buffer> object.

On Linux, when Node.js is linked against musl libc, the procfs file system mustbe mounted on/proc in order for this function to work. Glibc does not havethis restriction.

fs.rename(oldPath, newPath, callback)#

• oldPath<string> |<Buffer> |<URL>
• newPath<string> |<Buffer> |<URL>
• callback<Function>
  • err<Error>

Asynchronously rename file atoldPath to the pathname providedasnewPath. In the case thatnewPath already exists, it willbe overwritten. If there is a directory atnewPath, an error willbe raised instead. No arguments other than a possible exception aregiven to the completion callback.

See also:rename(2).

import { rename }from'node:fs';rename('oldFile.txt','newFile.txt',(err) => {if (err)throw err;console.log('Rename complete!');});copy

fs.rmdir(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object>
  • maxRetries<integer> If anEBUSY,EMFILE,ENFILE,ENOTEMPTY, orEPERM error is encountered, Node.js retries the operation with a linearbackoff wait ofretryDelay milliseconds longer on each try. This optionrepresents the number of retries. This option is ignored if therecursiveoption is nottrue.Default:0.
  • recursive<boolean> Iftrue, perform a recursive directory removal. Inrecursive mode, operations are retried on failure.Default:false.Deprecated.
  • retryDelay<integer> The amount of time in milliseconds to wait betweenretries. This option is ignored if therecursive option is nottrue.Default:100.
• callback<Function>
  • err<Error>

Asynchronousrmdir(2). No arguments other than a possible exception are givento the completion callback.

Usingfs.rmdir() on a file (not a directory) results in anENOENT error onWindows and anENOTDIR error on POSIX.

To get a behavior similar to therm -rf Unix command, usefs.rm()with options{ recursive: true, force: true }.

fs.rm(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object>
  • force<boolean> Whentrue, exceptions will be ignored ifpath doesnot exist.Default:false.
  • maxRetries<integer> If anEBUSY,EMFILE,ENFILE,ENOTEMPTY, orEPERM error is encountered, Node.js will retry the operation with a linearbackoff wait ofretryDelay milliseconds longer on each try. This optionrepresents the number of retries. This option is ignored if therecursiveoption is nottrue.Default:0.
  • recursive<boolean> Iftrue, perform a recursive removal. Inrecursive mode operations are retried on failure.Default:false.
  • retryDelay<integer> The amount of time in milliseconds to wait betweenretries. This option is ignored if therecursive option is nottrue.Default:100.
• callback<Function>
  • err<Error>

Asynchronously removes files and directories (modeled on the standard POSIXrmutility). No arguments other than a possible exception are given to thecompletion callback.

fs.stat(path[, options], callback)#

• path<string> |<Buffer> |<URL>
• options<Object>
  • bigint<boolean> Whether the numeric values in the returned<fs.Stats> object should bebigint.Default:false.
• callback<Function>
  • err<Error>
  • stats<fs.Stats>

Asynchronousstat(2). The callback gets two arguments(err, stats) wherestats is an<fs.Stats> object.

In case of an error, theerr.code will be one ofCommon System Errors.

fs.stat() follows symbolic links. Usefs.lstat() to look at thelinks themselves.

Usingfs.stat() to check for the existence of a file before callingfs.open(),fs.readFile(), orfs.writeFile() is not recommended.Instead, user code should open/read/write the file directly and handle theerror raised if the file is not available.

To check if a file exists without manipulating it afterwards,fs.access()is recommended.

For example, given the following directory structure:

- txtDir-- file.txt- app.jscopy