Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.readFile() method

Reference for fs.readFile() and fsPromises.readFile() in Node.js: read a whole file as a Buffer or string, encodings, flags, abort signals, errors and size limits.

fs.readFile() reads the entire contents of a file into memory without blocking the event loop, then hands the result to a callback. Without an encoding the result is a Buffer of raw bytes; with an encoding such as 'utf8' it is a string. The promise version, fsPromises.readFile() from node:fs/promises, does the same and is the form to prefer in new code.

Use it for files you are happy to hold in memory at once: configuration, templates, small data files. For large or unbounded input, use a stream (fs.createReadStream()) so memory stays flat.

NODE
import { readFile } from 'node:fs/promises';

const text = await readFile('notes.txt', 'utf8');

Try it

Node.js Promise and callback forms

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 Errors, flags and abort signals

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.readFile(path, callback)
fs.readFile(path, options, callback)
fsPromises.readFile(path, options?): Promise<Buffer | string>

// path:    string | Buffer | URL | integer (file descriptor, callback form) | FileHandle (promise form)
// options: string (encoding) | { encoding?: string | null, flag?: string, signal?: AbortSignal }
// callback: (error: Error | null, data: Buffer | string) => void
Name Description
path File name, file: URL, or an open file descriptor (a number, callback form only; the promise form takes a FileHandle instead). A descriptor is read from its current position to the end.
options.encoding Character encoding such as 'utf8', 'latin1', 'base64' or 'hex'. Default null, which returns a Buffer. A plain string argument is shorthand for this.
options.flag File system flag, default 'r'. See file system flags.
options.signal An AbortSignal to cancel an in-progress read. The read rejects with an AbortError.
callback Called once with (error, data).

Returns: the callback form returns nothing; the promise form resolves to a Buffer, or a string when an encoding is given.

Errors: ENOENT (no such file), EISDIR (path is a directory), EACCES (no permission), EMFILE (too many open files), ERR_FS_FILE_TOO_LARGE for a file over 2 GiB, and AbortError when cancelled. Errors carry code, syscall, path and errno.

Usage notes

  • The whole file is loaded. Memory use equals the file size (twice if you decode to a string, since a string is built from the bytes). Stream anything large.
  • Always pass an encoding for text. Forgetting it gives a Buffer, and console.log of a buffer prints <Buffer 48 65 ...>. Calling .toString() later assumes UTF-8.
  • The UTF-8 byte order mark is not stripped. A file saved with a byte order mark begins with ๏ปฟ, which breaks JSON.parse. Remove it with text.replace(/^๏ปฟ/, '') when you read files from Windows tools.
  • Relative paths use process.cwd(), not the folder of the script. Build absolute paths with import.meta.dirname (or __dirname in CommonJS) and path.join().
  • Do not check first. existsSync() followed by readFile() is a race. Call readFile() and handle ENOENT.
  • Promise or callback? The callback form is older and works everywhere; the promise form composes with await and Promise.all(). See Promises in fs.
  • Reads happen on the thread pool, so many parallel reads share four threads by default (UV_THREADPOOL_SIZE). Read thousands of files with a concurrency limit rather than all at once.
  • Use readFileSync() at startup, or in scripts where blocking does not matter.