Node.js v26.7.0 documentation

File system#

The node:fs module enables interacting with the file system in a way modeled on standard POSIX functions.

To use the promise-based APIs:

import * as fs from 'node:fs/promises';
const fs = require('node:fs/promises');
javascriptcopy

To use the callback and sync APIs:

import * as fs from 'node:fs';
const fs = require('node:fs');
javascriptcopy

All file system operations have synchronous, callback, and promise-based forms, and are accessible using both CommonJS syntax and ES6 Modules (ESM).

Promise example#

Promise-based operations return a promise that is fulfilled when the asynchronous operation is complete.

import { unlink } from 'node:fs/promises';

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}
const { unlink } = require('node:fs/promises');

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');
javascriptcopy

Callback example#

The callback form takes a completion callback function as its last argument and invokes the operation asynchronously. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation is completed successfully, then the first argument is null or undefined.

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});
const { unlink } = require('node:fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});
javascriptcopy

The callback-based versions of the node:fs module APIs are preferable over the use of the promise APIs when maximal performance (both in terms of execution time and memory allocation) is required.

Synchronous example#

The synchronous APIs block the Node.js event loop and further JavaScript execution until the operation is complete. Exceptions are thrown immediately and can be handled using try…catch, or can be allowed to bubble up.

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}
const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}
javascriptcopy

Promises API#

The fs/promises API provides asynchronous file system methods that return promises.

The promise APIs use the underlying Node.js threadpool to perform file system operations off the event loop thread. These operations are not synchronized or threadsafe. Care must be taken when performing multiple concurrent modifications on the same file or data corruption may occur.

Class: FileHandle#

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

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

All <FileHandle> objects are <EventEmitter>s.

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

Event: 'close'#

The 'close' event is emitted when the <FileHandle> has been closed and can no longer be used.

filehandle.appendFile(data[, options])#

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable>
• options <Object> | <string>
  • encoding <string> | <null> Default: 'utf8'
  • signal <AbortSignal> | <undefined> allows aborting an in-progress writeFile. Default: undefined
• Returns: <Promise> Fulfills with undefined upon success.

Alias of filehandle.writeFile().

When operating on file handles, the mode cannot be changed from what it was set to with fsPromises.open(). Therefore, this is equivalent to filehandle.writeFile().

filehandle.chmod(mode)#

• mode <integer> the file mode bit mask.
• Returns: <Promise> Fulfills with undefined upon success.

Modifies the permissions on the file. See chmod(2).

filehandle.chown(uid, gid)#

• uid <integer> The file's new owner's user id.
• gid <integer> The file's new group's group id.
• Returns: <Promise> Fulfills with undefined upon success.

Changes the ownership of the file. A wrapper for chown(2).

filehandle.close()#

• Returns: <Promise> Fulfills with undefined upon success.

Closes the file handle after waiting for any pending operation on the handle to complete.

import { open } from 'node:fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
}
mjscopy

filehandle.createReadStream([options])#

• options <Object>
  • encoding <string> Default: null
  • autoClose <boolean> Default: true
  • emitClose <boolean> Default: true
  • start <integer>
  • end <integer> Default: Infinity
  • highWaterMark <integer> Default: 64 * 1024
  • signal <AbortSignal> |