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.
import { readFile } from 'node:fs/promises'; const text = await readFile('notes.txt', 'utf8');
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.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, andconsole.logof 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 breaksJSON.parse. Remove it withtext.replace(/^๏ปฟ/, '')when you read files from Windows tools. - Relative paths use
process.cwd(), not the folder of the script. Build absolute paths withimport.meta.dirname(or__dirnamein CommonJS) andpath.join(). - Do not check first.
existsSync()followed byreadFile()is a race. CallreadFile()and handleENOENT. - Promise or callback? The callback form is older and works everywhere; the promise form composes with
awaitandPromise.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.